openclaw/docs/plugins/codex-supervision.md

---
summary: "Browse non-archived native Codex sessions and paginated transcripts across OpenClaw nodes"
title: "Supervise Codex sessions"
sidebarTitle: "Codex supervision"
read_when:
  - You want Codex Desktop or CLI sessions to appear in OpenClaw
  - You need to continue a stored or idle Codex session or archive a local one
  - You are exposing Codex sessions and transcript history from paired nodes
---

Codex supervision is an opt-in capability of the official `codex` plugin. It
shows non-archived Codex CLI, VS Code, Atlas, and ChatGPT source sessions from
the Gateway computer and opted-in paired computers in the normal sessions
sidebar and Chat pane.

Supported actions depend on the source host and its capabilities:

- A stored or idle local session can create a model-locked OpenClaw Chat from
  its bounded persisted user and assistant history. The first message starts a
  native snapshot fork, then starts the full Codex harness thread with exactly
  the model and provider that Codex App Server selected for that fork. Later
  turns restore the canonical native thread's persisted pair while the
  supervised binding prevents OpenClaw from substituting another runtime,
  model, or fallback. A separate native Codex control can still change that
  persisted pair. An already-created branch opens its existing Chat.
- A stored local session discovered from another Codex process has unknown live
  activity. It can branch, or it can be archived only after the operator
  confirms that no other Codex client is using it.
- An active source stays visible but cannot create a branch or be archived until
  its current turn finishes. If it already has a supervised Chat, **Open Chat**
  remains available.
- A session on a paired node exposes its persisted transcript through bounded,
  cursor-paginated App Server reads. A stored or idle interactive session can
  also continue in Chat when the node permits the required catalog and
  CLI-resume commands and the operator has `operator.admin`. Later messages
  resume the exact native thread on that node, not a Gateway-local branch.
  Paired-node archive remains unavailable.
- Archived sessions are not listed. A stored or idle local session can be
  archived only after the operator confirms that no other Codex client is using
  it.

## Before you begin

- Install the official `@openclaw/codex` plugin on the Gateway. The OpenClaw
  macOS app can install it when you enable Codex features. CLI installations can
  run `openclaw plugins install @openclaw/codex`.
- Install and sign in to Codex Desktop or the Codex CLI on each computer whose
  sessions you want to list.
- Pair remote computers as OpenClaw nodes. Each computer must opt in locally.
  Enabling supervision only on the Gateway does not authorize another node.
- Use an owner-controlled Gateway. Session titles, working directories, and Git
  branches can reveal sensitive project information.

## Enable supervision

Guided `openclaw onboard` and macOS first-run setup attempt to install and
enable Codex supervision after detecting a native Codex installation and
successfully activating the selected inference backend. Codex does not need to
be the primary backend. Supervision becomes available when that opportunistic
plugin activation succeeds. App Server availability is checked when
supervision first connects. An explicit Codex plugin disable or policy block
prevents opportunistic activation, and an existing explicit
`supervision.enabled: false` disables agent-facing supervision tools. The
operator catalog remains registered whenever the Codex plugin is active unless
`sessionCatalog.enabled: false` disables it. This separate switch leaves the
Codex provider, harness, and agent-facing supervision policy unchanged while
also removing the paired-node catalog list/read commands from this host.
Existing installations can enable the same capability manually:

Enable the `codex` plugin and its supervision capability in `openclaw.json`:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          supervision: {
            enabled: true,
          },
        },
      },
    },
  },
}
```

If `plugins.allow` is present, include `codex`. Gateway plugin activation applies
automatically in the default hybrid reload mode; see
[Apply changes and inspect](/plugins/manage-plugins#apply-changes-and-inspect).

With no explicit `appServer` connection settings, supervision uses managed
stdio connections for the available local Codex stores. The catalog combines
the process user's `CODEX_HOME` with existing `codex-home` stores under configured
OpenClaw agent directories, deduplicates canonical paths, and assigns each store
an opaque local host id. Each store gets its own App Server connection. Its path
is never exposed in the catalog. List, read, continue, archive, adopt, and
terminal resume keep the selected source while retaining the explicit OpenClaw
route agent as owner. The ordinary Codex harness remains agent-scoped by default.
Set `appServer.homeScope: "user"` explicitly if the harness should share native
Codex state too. Supervision honors explicit `appServer` connection settings
instead of replacing them with its local user-home default.

To share a running local daemon and its existing `config.toml` and login, use
the [local Codex configuration setup](/plugins/codex-harness/native-features#use-an-existing-local-configtoml).

Catalog reads use the selected store's native Codex authentication, including
when that store is under an OpenClaw agent directory. Browsing stored sessions
does not require importing a native credential into OpenClaw. Ordinary managed
agent runs retain their own credential-import and authentication requirements.

A Gateway-local Chat adopted from the **Codex** sidebar group is not an ordinary harness session.
Its private supervision binding uses the supervision connection for source
reads, canonical branch creation, history injection, and every later turn. With
the default local connection, that preserves the native user Codex home, auth,
and provider configuration without changing the default for other sessions.
Watched adopted Chats also participate in [session state awareness](/concepts/session-state).

For the default local supervision connection, the store is shared with native
Codex clients. OpenClaw does not assume that another client shares the same live
App Server process, and native status ownership is process-local. It therefore
treats a thread that its supervision App Server reports as `notLoaded` as
**Stored / activity unknown**, not as idle.

Apply the same opt-in on every headless node host whose sessions should appear.
The native OpenClaw macOS app reads the same local setting when it advertises
its Codex catalog to the paired Gateway. That paired native Mac catalog supports
only the default or explicit `appServer.transport: "stdio"` with an unset or
explicit `appServer.homeScope: "user"`. `command`, `args`, and `clearEnv` are
honored for that stdio process. If the Mac config selects `"unix"`,
`"websocket"`, or `homeScope: "agent"`, the app does not advertise the catalog
capability or command, and a stale direct invocation fails instead of exposing
the user Codex home or spawning a different local stdio App Server.

Headless nodes default to their native user-home stdio catalog: `CODEX_HOME`,
or `~/.codex` when it is unset. Native listing, transcript reads, terminal resume,
and Chat continuation use that same node-owned store. A Gateway agent need not
exist on an updated native node, even when the node has multiple agents and no
default owner.

Gateways retain the optional `agentId` field for interoperability with released
nodes that still require it. Updated native readers treat that field as route
context only. Explicit agent-scoped or non-stdio catalog configurations retain
their existing source-selection contract: the requested owner selects the
configured node source, and a missing or removed owner fails instead of falling
back to the native user home. Upgrade the node as well as the Gateway to obtain
agent-independent native discovery.

A newly advertised node command changes the node's approved command surface.
Approve the update from the Gateway host:

```bash
openclaw nodes pending
openclaw nodes approve <requestId>
```

Non-archived Codex sessions also appear in the main Control UI sidebar, grouped
by host. Select one to read its persisted transcript. Each request returns at
most 50 transcript items (20 when the caller omits `limit`), with smaller pages
when needed for the 20 MiB transport safety ceiling. Supported stores use Codex
`thread/items/list`. Older stores and node readers retain `thread/turns/list`
with paging inside a turn. Scroll upward to load older pages. Loaded
pages render in chronological order.

The Control UI shows tool results as 500-character previews and marks shortened
output. Previewing does not rewrite the native transcript or remove generic
`raw` data. Catalog text uses the shared 512 KiB per-item bound. The viewer never
loads an unbounded `thread/read` history. A legacy turn response or individual
item above the transport ceiling still fails visibly. Open that session in
Codex to inspect its full output.

Open the **Codex** group in the normal sessions sidebar. It lists the same sessions
grouped by host. **Load more sessions** appends the next page from each host that
has older rows, and those appended rows survive the sidebar's periodic refresh.
Each host appears as soon as its resident catalog is ready. The visible page
reconciles after node-connectivity changes, when it regains focus, and at most
every 30 seconds. A changed result gets a faster follow-up pass. Sessions created
in Codex Desktop, the CLI, or another native client appear after the host's
background directory reconciliation. Native events update threads driven by that
Gateway without waiting for the periodic scan. Searches and pagination use the
resident rows while the home fits in memory. The 20,000-row retained window never
limits discovery: older pages and scoped searches fall back to native database-only
paging, with opaque continuations for bounded partial results. An empty partial
search page can still have a continuation. Exact-thread access also verifies older
IDs against the authoritative source instead of treating eviction as absence.
The first page follows recency order, preserving native order within timestamp ties and using a stable
thread key for pagination. A fresh native fork remains readable by ID but can be absent from
these lists until its first own user turn. See [catalog hydration and bounds](/plugins/codex-harness).

Host availability and thread status are separate. **Offline** or **Unavailable**
describes a host refresh. An unavailable host returns no fresh session rows and
does not change a thread's native status to `offline`. Session rows use Codex
statuses such as `idle`, `active`, `notLoaded`, or error. A failed host does not
hide results from healthy hosts.

All queries of the same local home share one resident index. Initial native
hydration uses the existing source failure backoff; completed rows remain in
memory and in the reconstructible SQLite snapshot. Normal list requests never
restart discovery after a TTL. Progressive sidebar lists reuse the last published
paired-node page for the same query and refresh it in the background. A node
without a matching page gets up to 250 ms to answer; after that its host is marked
pending, preserving visible rows until the existing host update event arrives.
Node disconnects, reconnects, configuration changes, and newer publications
invalidate retained pages. Older refreshes cannot replace a newer publication.
One-shot lists, host-specific lookups, and pagination still await fresh node data
under the existing eight-second response deadline.

The sidebar hides the Codex group when it has no visible sessions, including
when discovery fails. Normal discovery refreshes continue, so the group appears
when sessions become available. A populated group remains visible when another
host fails.

The sidebar warning includes the catalog error code and the safe underlying
Gateway error. Open the sidebar's **Filter & sort > Session sources…** menu,
or **Settings > Appearance > Session sources**, and turn off **Show Codex sessions**
to disable discovery without disabling Codex. For
`NODE_LIST_FAILED`, compare `openclaw nodes list` and **Settings > Devices**.
The detailed cause identifies the pairing-store, node-registry, permission, or
Gateway lifecycle failure that needs repair.

## Start a new native Codex CLI

Select **+** beside **Codex**, choose a native host and folder, then press
**Start in terminal** or Enter. This launches a new interactive Codex CLI, not
a model-locked OpenClaw Chat or an adopted native thread. Codex owns its native
account, model, configuration, and session identity. The optional prompt is
passed as text, never as CLI options. Local catalog sources preserve their
selected Codex home, including opaque secondary local host IDs.

Terminal creation requires `operator.admin`, `gateway.cliAgents.enabled`, the
installed CLI, and the active catalog plugin. Terminals are enabled by default.
`gateway.terminal.enabled: false` blocks creation.
It does not require an eligible OpenClaw model. A paired headless node must
advertise and permit **`codex.terminal.start.v1`**. The existing
`codex.terminal.resume.v1` alone does not support fresh starts. The node chooses
its own installed Codex executable and native account/configuration. The Gateway
agent remains the authorization context. It need not exist in the node's
OpenClaw configuration.

Local starts support the Gateway folder/worktree chooser. Node starts require
an existing absolute directory on that node and never substitute the node's
home if it disappears. Commands accept only cwd, an optional prompt, and terminal
dimensions, not caller-supplied executables, argv, environment, or credentials.
Closing the terminal cancels its node invocation. Disconnects and stale pairing
or connection generations are handled by the same terminal relay as resume.
Opening an existing session in a terminal also requires a local stdio source or
a paired node that advertises terminal resume. Unix and WebSocket catalogs
connected directly to the Gateway remain available for browsing and Chat
continuation. For terminal access, open a native client configured for that server.
See [native CLI creation](/web/control-ui/sessions-and-sidebar#start-a-native-coding-cli) for UI controls
and prerequisites. Existing catalog viewing, resume, and Chat continuation keep
their separate ownership contracts.

## Use the operator CLI

The terminal CLI exposes the same non-archived catalog and Gateway-local branch
and archive actions:

```bash
openclaw codex sessions [--agent <id>] [--search <text>] [--host <id>] [--limit <count>] [--cursor <cursor>] [--json] [--url <url>] [--token <token>] [--timeout <ms>] [--expect-final]
openclaw codex continue <thread-id> [--agent <id>] [--host <id>] [--json] [--url <url>] [--token <token>] [--timeout <ms>] [--expect-final]
openclaw codex archive <thread-id> --confirm-no-other-runner [--agent <id>] [--host <id>] [--json] [--url <url>] [--token <token>] [--timeout <ms>] [--expect-final]
```

`openclaw codex sessions` options:

- `--agent <id>` selects the OpenClaw owner in a multi-agent Gateway.
- `--search <text>` searches session titles case-insensitively.
- `--host <id>` limits the response to one stable catalog host, such as
  `gateway:local`, an opaque `gateway:local:<source-id>`, or `node:<node-id>`.
- `--limit <count>` sets 1 through 100 rows per host. The default is 50.
- `--cursor <cursor>` continues one host page and therefore requires `--host`.
- `--json` prints the structured Gateway response.

All three commands accept `--agent <id>` and inherit `--url`, `--token`, and `--timeout <ms>` from the
Gateway client. Session listing defaults to 75,000 ms so cold paired-node
catalogs can complete. Continue and archive default to 30,000 ms. They also expose the shared
`--expect-final` switch, which does not change these unary supervision RPCs.
Each shell command requests the `operator.write` Gateway scope.
Standard `-h, --help` output is available on each subcommand.
There is no archived or include-archived option. `sessions` can list paired
hosts. `continue` and `archive` default to `gateway:local`. Pass the listed
opaque local `--host` id to target another local Codex store. The shell
`continue` command requests only `operator.write`. Passing a node host does not
request the `operator.admin` scope required for paired-node continuation. Unless
the Gateway separately grants that scope to the authenticated identity, the
request is refused. Use the admin-authorized Control UI flow described below
for paired-node continuation. Archive remains Gateway-local and always requires
`--confirm-no-other-runner`.

These shell commands are distinct from the in-chat `/codex` runtime commands.
`/codex threads [filter]` lists App Server threads available to the current
conversation connection. `/codex sessions --host <node>` lists resumable Codex
CLI session files on one node, not the supervision fleet catalog. `/codex
resume` and `/codex bind` attach the current conversation instead of creating a
safe supervised branch, and a model-locked supervised Chat rejects those
binding mutations. There is no `/codex continue` or `/codex archive` runtime
command.

## Branch from a local session

Open a stored or idle session from the Gateway computer in the **Codex** sidebar
and send a message from its session viewer. OpenClaw creates a model-locked Chat
entry, mirrors bounded user and assistant history through the source's last
terminal persisted turn (completed, interrupted, or failed), records a pending
harness branch, and forwards your message to the Chat. The generic model picker
stays locked.
Branch preparation does not resume the source or start the canonical harness
thread; the forwarded message starts that work. Continuing the same source
opens its existing Chat instead of creating another branch.

The mirror keeps the newest visible tail that fits all three limits: at most 200
user or assistant messages, 512 KiB of UTF-8 text in total, and 64 KiB per
message. Oversized messages are truncated with a marker, and older messages are
omitted when a cap is reached. An image or local-image input becomes the literal
`[Image attachment]` placeholder. Image data and local paths are not copied.

The first forwarded message begins work. The Codex harness installs the
real approval, elicitation, event, and delivery handlers. It uses an ephemeral
native fork on the supervision connection to pin the source snapshot without
supplying a model or provider override. Codex App Server selects both from its
current native configuration and returns the actual selection. OpenClaw confirms
the probe's subscription is released before creating the canonical branch. The
probe never becomes stored history or an archive artifact. On that same
connection, OpenClaw starts the canonical `appServer`-source full harness thread
under its cwd and runtime policy with exactly that returned pair, injects the
bounded visible history, and commits the branch binding. The canonical thread
has the full OpenClaw harness tool surface. This is a visible-history branch, not
a full native rollout clone: source reasoning, tool calls, and tool results are
omitted. This and every later turn stays on the supervised Codex connection
rather than another OpenClaw model runtime or the ordinary agent-home harness.

The returned selection is not proof of the source's historical model. If the
current native configuration differs from the model recorded for the source's
last turn, Codex emits its normal model-difference warning. OpenClaw uses the
returned pair for the canonical thread start. Codex persists that canonical
thread's native model and provider, and later resumes preserve them because
OpenClaw omits model and provider overrides. If the canonical thread is changed
through a separate native Codex control, OpenClaw accepts Codex's persisted
selection. OpenClaw never substitutes its outer model or fallback chain.

The supervised model-locked Chat cannot be deleted, switch models, use `/new`
or `/reset`, invoke the Gateway session-reset action, or use the generic
**Fork session** action. Mutating `/codex model <model>`, `/codex
bind`, `/codex resume` (including a node session with `--bind here`), and
`/codex detach` or `/codex unbind` are also rejected because they would replace
or clear the locked native binding. The `/codex model` query and `/codex fast`,
`/codex permissions`, and `/codex threads` remain available. Start another
ordinary session when you want a different model or fresh thread.

**Fork from here** keeps the source connection and model-locked harness without
changing the original source or parent Chat. Original imported messages and
canonical conversation messages use different native flows. See
[Fork a message in a supervised Chat](/plugins/codex-supervision#fork-a-message-in-a-supervised-chat).

Keep supervision enabled for this Chat. If supervision is disabled or its
stored connection binding becomes unavailable or inconsistent, the turn fails
closed instead of moving to an ordinary agent-home session.

A new adoption snapshots the native title as a trimmed display name, capped at
500 UTF-16 code units without splitting surrogate pairs. Native titles can be
duplicated or blank. They do not claim unique OpenClaw labels. An explicit local
label takes priority over the stored display name. Reopening or recovering a Chat
preserves its existing label and title snapshot, including older automatically
assigned labels. Renaming the native source does not resync either field.
**Fork from here** does not inherit the native response's title as a display name
or local label.

Disabling or uninstalling the `codex` plugin does not release that ownership or
make the Chat eligible for another model. The locked Chat remains preserved but
unavailable. Reinstall or re-enable the same plugin, confirm runtime application,
then resume it. This deliberate fail-closed behavior prevents retention cleanup or a
temporary plugin outage from silently orphaning the native binding.

The `codex_threads` agent tool follows the same boundary. It cannot attach a
different fork or archive the Chat's bound native thread. List and metadata-only
read remain available. Raw transcript reads require `allowRawTranscripts`.
When raw access is disabled, `codex_threads` also rejects list search because
native search includes transcript previews. The Control UI and operator CLI
still provide bounded title-only search. Rename, unarchive, detached fork, and
archive of an unrelated unowned thread require
`allowWriteControls`. Neither option bypasses the locked binding.

OpenClaw does not subscribe to or answer approval requests while merely listing
the source thread or displaying the pending Chat. Starting a distinct canonical
harness thread on the first turn lets another Codex process keep owning the
source without creating competing rollout writers.

The original CLI, VS Code, Atlas, or ChatGPT source remains visible to native
clients and the OpenClaw catalog. The canonical branch is stored as a native
Codex thread, but its source kind is `appServer`. Codex Desktop or another
native client may filter that source kind, so the branch itself is not guaranteed
to appear in every native history view.

An active row reported by OpenClaw's App Server cannot start a new branch. Wait
for the current turn to finish and refresh the catalog. Codex App Server
serializes mutations within one process, but it does not provide an exclusive
cross-process runner or approval-owner lease.

For a **Stored / activity unknown** row, the Chat mirror and first-turn snapshot
pin use Codex's state through the last terminal persisted turn. The source
thread is not resumed, interrupted, or archived. If another process has an
in-progress turn, its latest in-flight work might not be present in the branch.

## Fork a message in a supervised Chat

Forking an original imported user message keeps the original-source flow: the
source must still be readable, and the child's first turn materializes its
bounded imported history.

Forking a user message created in the canonical OpenClaw conversation instead
creates a native child immediately, cut before that native turn. Codex retains
its raw history, including the originally injected prefix, without another
history import. The local Chat copies only the verified display prefix before
the selected message and keeps the original source link. Activity monitoring
starts after the retained native prefix, so inherited messages do not appear as
new human input. This canonical cut does not require the original imported
source to remain available.

New canonical user turns record native prompt provenance on the existing Chat
message after Codex accepts the prompt. This preserves the message ID, text,
timestamp, sender metadata, and position. Older canonical turns that lack this
provenance remain unverifiable: matching text or an adjacent assistant reply
cannot establish the missing native boundary. A later verified turn does not
repair an earlier unverifiable prefix. Start a fresh Chat from the original
source, or fork an original imported message while that source remains
available, then create new canonical turns. OpenClaw does not backfill old rows.

Canonical message forks use the shipping Codex App Server's developer-message
API. OpenClaw keeps the complete current generic instructions in native thread
configuration and appends one developer message that replaces earlier
OpenClaw-supplied generic policy, including removed sections or an explicit
empty policy. Independent native managed, guardian, security, collaboration,
and project instructions retain their authority. This is textual supersession.
It does not delete earlier history or change native permission enforcement.

The refresh is session configuration recorded before the next native user turn.
It can contain prompt-hook output for that request and remains in native history
even if the user turn is rejected or never starts. **Fork from here** excludes
the selected native user turn. It does not erase configuration updates recorded
before that turn. The refresh creates no user message or extra model turn.

Canonical message forks require Codex 0.153.0 or newer and native model metadata.
They use the source thread's current model selection when loaded in the selected
App Server, or its latest persisted selection when unloaded. If Codex cannot
report that selection, update Codex or fork an original imported message instead.

Before publishing the child, OpenClaw verifies the native cut, selected model
and provider, immutable tool catalog, local display prefix, and exact creation
owner. It rejects changes to the source rollout or selected model during
initialization. Its automatic native subscription is released before readiness.
Preparation does not run prompt hooks or provision execution environments or
requester MCP resources. The source's actual native declarations must match the
fresh child's declarations. Creation does not reconstruct a hypothetical run's
tools. A child whose native policy or metadata cannot be verified is refused
with an original-message alternative. Display copies are limited to 200 messages
and 512 KiB of serialized message data.

Inherited declarations do not grant permission to execute tools. Every admitted
turn builds its currently available tools and approvals independently. A tool
that is unavailable to a nonowner or a closed run remains unavailable, while the
native descendant retains its catalog and history across turns and restarts.

A creator-required sandbox needs a host-provisioned environment and is therefore
not eligible for this direct canonical fork. Codex workspace-write alone does
not satisfy that isolation requirement.

Later turns require native unload evidence before applying current harness
configuration. An unsubscribe acknowledgement alone does not establish that
the thread unloaded. Once configuration is proven, OpenClaw refreshes the
complete generic policy before starting the turn. Stop competing native work
and reconnect if configuration application cannot be verified. The bound
conversation is preserved. An uncertain refresh also preserves the conversation
and retires its connection rather than replaying the operation. A failed fresh
child with unverified cleanup remains non-ready for inspection.

Fresh initial materialization already supplies generic instructions and needs
no additional policy refresh. Ordinary nonsupervised sessions keep their existing
resume and warm-reuse behavior. Standalone cold compaction, review, and goal
operations do not reconstruct the last run's hook-derived generic policy. The
next admitted supervised run supplies current configuration and refreshes it.

## Archive a local session

Choose **Archive** on a stored or idle Gateway-local row, then confirm that no
other Codex client or OpenClaw runner is using that thread or its spawned
descendants. OpenClaw freshly reads the process-local status, proceeds only for
`idle` or `notLoaded`, calls the native Codex archive operation, and removes the
session from the non-archived list. Native Codex also attempts to archive the
thread's spawned descendants and stops archived descendants that were resumed
through native collaboration.

Archive is unavailable when the fresh read reports the session active or in an
error state, when it belongs to a paired node, or while a newly created
supervised Chat still has a pending branch from that source. Send the Chat's
first message to materialize its canonical branch before archiving the source.
Archive is also blocked when OpenClaw knows that an active binding owns the
exact target thread or any spawned descendant, including archived descendants.
OpenClaw checks both descendant collections for active work and follows the
experimental Codex descendant query through every page within one shared bound. An invalid response,
request failure, repeated cursor or thread, or safety-limit exhaustion rejects
archive.

The read, descendant enumeration, and archive requests are not one conditional
operation, so a turn can still start between them. App Server status is also
not shared across independent processes. The confirmation is therefore the
safety boundary for unknown clients and that race: quit or otherwise verify
every other client before confirming. Restore an archived thread with Codex
Desktop, the Codex CLI, or an owner-authorized native thread-management flow.
It reappears after unarchive.

```bash
codex unarchive <thread-id>
```

## Understand paired-node limits

Paired nodes expose the versioned read-only
`codex.appServer.threads.list.v1` and
`codex.appServer.thread.turns.list.v1` commands. Native node hosts with the
Codex CLI available also expose the allowlisted `codex.terminal.resume.v1`
command. The Gateway receives normalized
metadata and explicitly requested bounded transcript pages, never raw App Server
endpoints. Opening a row in the operator terminal runs `codex resume <thread-id>`
on the owning host and relays that command's PTY. It does not expose a general
shell or gateway-supplied argv.

Chat continuation is a separate capability from the terminal relay. It requires
`operator.admin` and a connected node that both advertises and permits all three
commands:

- `codex.appServer.threads.list.v1`
- `codex.appServer.thread.turns.list.v1`
- `codex.cli.session.resume`

The node must also advertise support for resuming the selected catalog source.
Paired-node Chat continuation requires that source to use local stdio; Unix and
WebSocket sources remain browsable but cannot be continued through the node's CLI.
If OpenClaw requests an upgrade, update the node and approve its refreshed
capabilities. Older nodes remain available for browsing; the existing Chat is
preserved. Legacy CLI bindings that resume the node's native user home retain
their existing behavior.

New paired-node Chats pin the selected canonical Codex home as well as the node
and thread. Changing a node's catalog source cannot redirect an existing Chat,
even when the replacement home contains a copied thread with the same ID.
Restore the original source to continue that Chat, or select the replacement
source in the catalog to adopt it into a separate Chat.
OpenClaw captures each source's physical path for the current configuration;
retargeting a directory alias takes effect after configuration reload.

Chats adopted by older versions did not record their source home. Their history
remains available, but native continuation requires a fresh adoption from the
catalog. OpenClaw creates a separate pinned Chat and preserves the older Chat;
it does not infer the older Chat's home from the node's current configuration.

The CLI-resume command is a dangerous node command: it needs explicit Gateway
command allowlisting (`gateway.nodes.commands.allow`) as well as approval of
the node's command surface. A deny rule still blocks it. The native macOS catalog
and terminal relay alone do not provide it, although a Mac app's embedded node
worker can advertise additional commands. Check the actual advertised and
permitted commands, not just the host platform. Nodes exposing only list,
transcript, and terminal commands remain readable without Chat continuation.

Open an eligible non-archived interactive row in the Control UI Chat pane and
send a text message. Continuation freshly checks that the source is `idle` or
`notLoaded`, creates or reopens a model-locked Chat, and binds it to the exact
native thread on the owning node. A new Chat mirrors bounded user and assistant
history from the newest transcript page. The catalog action itself does not
fork or resume the native thread. The UI then forwards your draft to the bound
Chat. That message and later turns run `codex exec resume` on the node with its
native CLI configuration and return its final text. This text-prompt path does
not create the Gateway-local branch or forward the full App Server harness
events, approvals, tool calls, or structured attachments. Bound turns still
require owner/admin authority and are blocked while OpenClaw sandboxing is active.

Avoid running the same thread in another Codex client while using this Chat.
The node prevents overlapping OpenClaw resume turns for the same thread and
canonical store within its own process, but
`notLoaded` does not prove that another native client is idle and there is no
cross-process runner lease. Paired-node **Archive** remains unavailable,
regardless of continuation or terminal capabilities.

## Metadata and permissions

Catalog rows may include:

- thread and session identifiers
- title and working directory
- current status and active wait flags
- created, updated, and activity timestamps
- source, model provider, Codex CLI version, and Git branch

Catalog projection excludes transcript previews, turns, rollout paths,
the Codex home path, Git remotes, commit SHAs, and raw App Server errors. Catalog
access and Control UI transcript reads require the `operator.write` Gateway
scope because fleet aggregation uses the standard `node.invoke` path, even
though both catalog node commands are read-only. Paired-node continuation
additionally requires `operator.admin`. Subsequent bound turns enforce the
native-execution owner/admin check.

`supervision.allowRawTranscripts` and `supervision.allowWriteControls` govern
autonomous agent and standalone MCP tools. Both default to `false`. With
supervision enabled, `codex_threads` removes transcript previews and turns from
list and metadata-only read results unless raw transcripts are allowed. A
turn-inclusive read fails closed. Every fork, rename, archive, and unarchive
requires write controls. These options do not gate authenticated Control UI
transcript viewing and do not bypass binding, host, status, or confirmation checks.

### Compatibility tools

The official `codex` plugin retains the five shipped Supervisor tool names for
existing agent and standalone MCP clients:

- `codex_endpoint_probe`
- `codex_sessions_list`
- `codex_session_read`
- `codex_session_send`
- `codex_session_interrupt`

`codex_sessions_list` is loaded-only by default. There is no `loaded_only`
parameter. Set `include_stored: true` to also read non-archived stored rows from
Codex's state database. The optional `max_stored_sessions` cap defaults to 200
and accepts 1 through 1,000 rows per endpoint. It does not cap loaded rows.
Without raw-transcript permission, list results omit transcript-derived names,
previews, and detailed endpoint errors.
`codex_session_read` requires `allowRawTranscripts`. `include_turns: true`
additionally asks Codex for turns.

`codex_session_send` and `codex_session_interrupt` require
`allowWriteControls`. Send accepts `mode: "auto" | "start" | "steer"`, but
`"start"` is always refused and both `"auto"` and `"steer"` can only steer a
readable active turn. An idle thread is refused with guidance to use **Codex
Sessions**, where the full harness installs approval and tool handlers before
continuation. Interrupt likewise requires an active readable turn. These tools
do not resume or start an idle source thread.

`openclaw doctor --fix` moves a retired `codex-supervisor` entry, its endpoint
and permission fields, and plugin allow/deny policy references into the official
`codex` plugin without overwriting explicit canonical settings. The standalone
compatibility MCP adapter continues to load the same five tools from that
plugin. Legacy policy environment variables apply only inside that trusted
adapter.

For every supervision config field, see
[Codex harness reference](/plugins/codex-harness-reference#supervision).

## Troubleshooting

**No sessions appear:** verify that `@openclaw/codex` is installed, both the
plugin and `supervision.enabled` are true, the current plugin allowlist permits
`codex`, and the sessions are not archived. Gateway activation changes hot-apply;
refresh the catalog after they finish. Restart a node if its local activation
change has not refreshed its advertised capabilities.

**Continue is disabled or refused:** an unmapped row is active or in an
ineligible state, its host is offline, or another action is pending. For a
paired-node row, also verify `operator.admin` and that all three continuation
commands are advertised and permitted. Terminal access alone is insufficient.
Send from a Gateway-local stored or idle session viewer to create a separate
branch. Continuing a source that already has a supervised Chat opens that Chat.

**Session eligibility could not be verified:** for filesystem-backed local
sources, transcript, Continue, Archive, and terminal actions verify the selected
thread directly, check non-archived native index membership, and validate its
rollout metadata in the selected Codex home. These checks share one request
budget and do not scan the full catalog. Missing, unreadable, inconsistent, or
OpenClaw-managed metadata is not accepted. Refresh the catalog, verify the session
in its native Codex home, and retry. This error does not prove that the thread
does not exist. Ordinary discovery keeps its existing behavior. Remote sources
continue to use fresh native catalog verification, including when the requested ID
is still resident or was evicted. Neither remote nor paired-node verification stops at a fixed
catalog page count; the existing request deadline still bounds the operation.

**Archive is disabled:** archive is available for stored/activity-unknown and
idle Gateway-local rows after no-other-runner confirmation. Active, error,
offline, paired-node, pending-branch, and known exact-binding-owner rows remain
read-only for archive.

**An archived session disappeared:** this is expected. The supervision page has
no archived view. Run `codex unarchive <thread-id>` or use Codex Desktop to show
it again.

**Old `codex-supervisor` config remains:** run `openclaw doctor --fix`. Doctor
moves the retired plugin entry and related plugin-policy references into
`plugins.entries.codex.config.supervision` without overwriting explicit Codex
settings.

## Related

- [Codex harness](/plugins/codex-harness)
- [Codex harness reference](/plugins/codex-harness-reference)
- [Codex harness runtime](/plugins/codex-harness-runtime)
- [Codex supervision architecture](/specs/codex-supervision)
- [Nodes](/nodes)
- [Gateway security](/gateway/security)