Codex supervision

Codex supervision 문서는 OpenClaw 공식 문서(specs/codex-supervision)를 한국어로 정리한 가이드입니다. Architecture and product boundary for supervising native Codex sessions from OpenClaw. 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Architecture and product boundary for supervising native Codex sessions from OpenClaw.

한국어 가이드 범위: specs/codex-supervision 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Codex supervision
Goal
Product boundary
Ownership
Catalog flow
Operator CLI boundary
Local continuation
Archive behavior
Active thread safety
Paired-node boundary
Permissions
Compatibility
Future work
Acceptance tests

상세 내용

Codex supervision

이 섹션의 세부 항목은 공식 문서 Codex supervision를 참고하세요.

Goal

Codex supervision lets an OpenClaw operator discover native Codex sessions and, when safe, create a local branch through the normal OpenClaw Chat surface. Codex App Server remains the thread and model-loop owner. OpenClaw supplies the fleet catalog, authenticated operator UI, session binding, and channel delivery.

Product boundary

The catalog registers whenever the Codex plugin is active unless native session discovery is explicitly disabled with:

주요 항목:

List only non-archived Codex threads.
Group local and opted-in paired-node rows by stable host identity.
Create a normal, model-locked Chat branch from a stored or idle Gateway-local
Archive a stored or idle Gateway-local thread only after explicit
Show active local sources without new-branch or archive controls while still
Show the newest rows per host in the main sidebar, keep the full catalog on
Isolate catalog failures by host.

plugins.entries.codex.config.sessionCatalog.enabled = false

plugins.entries.codex.config.supervision.enabled = true

Ownership

The codex plugin owns all Codex App Server behavior:

주요 항목:

endpoint discovery and connection lifecycle
protocol initialization and version checks
thread list, read, resume, archive, and event handling
approval and user-input bridges
native thread bindings to OpenClaw sessions
Codex-only model and harness enforcement after continuation

Codex Desktop -> private stdio App Server -> user Codex home
                                             ^
OpenClaw Codex plugin -> supervision App Server connection
  (defaults to managed user-home stdio; explicit appServer settings are honored)
  -> passive source catalog and read
  -> snapshot pin -> canonical appServer-source branch
  -> visible-history injection and every later supervised Chat turn

Ordinary OpenClaw Codex sessions -> managed agent-home stdio by default
  -> ordinary full harness threads -> OpenClaw Chat and channel delivery

Catalog flow

The generic Gateway method sessions.catalog.list dispatches to the codex catalog provider, which always requests archived: false and lets App Server apply its interactive-source default: cli, vscode, Atlas, and ChatGPT. It combines:

Operator CLI boundary

The plugin registers three Gateway-backed shell commands:

openclaw codex sessions [--search <text>] [--host <id>] [--limit <count>] [--cursor <cursor>] [--json] [gateway-options]
openclaw codex continue <thread-id> [--json] [gateway-options]
openclaw codex archive <thread-id> --confirm-no-other-runner [--json] [gateway-options]

Local continuation

For a stored or idle Gateway-local row, the UI calls sessions.catalog.continue with catalogId: "codex" plus the host and thread ids. The plugin:

Archive behavior

For a stored or idle Gateway-local row, sessions.catalog.archive with catalogId: "codex" requires explicit confirmNoOtherRunner: true, freshly reads current process-local status, proceeds only for idle or notLoaded, calls native thread/archive, and returns success only after Codex accepts the operation. The row then leaves the non-archived catalog.

Active thread safety

Codex serializes mutations for a thread among clients of one App Server, but it does not expose an exclusive cross-process runner or approval-owner lease. Independent stdio App Servers can append to the same rollout, while each sees only its own in-memory status. Approval requests can also reach every subscriber of one server, with the first valid response completing the request.

주요 항목:

passive catalog clients do not subscribe or auto-deny approvals
rows currently reported active expose neither a new branch nor Archive
an unmapped source becomes a visible-history branch whose canonical harness
notLoaded is shown as activity unknown and can be archived only after
local archive requires that confirmation plus a fresh idle or notLoaded

Paired-node boundary

Node invoke is currently request/response only. It can safely return bounded catalog metadata and transcript turn pages, but it cannot carry the long-lived event stream, approval requests, tool calls, cancellation, and assistant deltas required by a Codex harness run.

Permissions

Each computer opts in locally. Enabling the Gateway does not authorize another node to read its Codex metadata. The node capability must pass normal pairing and command-policy approval.

Compatibility

openclaw doctor --fix migrates shipped plugins.entries.codex-supervisor configuration, including endpoints and transcript/write policies, plus plugin allow/deny references into plugins.entries.codex.config.supervision. Explicit canonical destination values win conflicts. Runtime code uses only the canonical codex plugin shape after migration.

Future work

Archived browsing is not part of the planned supervision sidebar. Native Codex surfaces remain the recovery path for archived threads.

주요 항목:

node-side streaming runner and event bridge for remote continuation
explicit runner and approval-owner leases for simultaneous client handoff
remote archive after a runner-ownership lease or equivalent fencing exists
interrupt and richer active-session observation
audited handoff between Codex Desktop, CLI, and OpenClaw

Acceptance tests

returns no fresh rows instead of inventing an offline session status.

주요 항목:

Enabling supervision lists non-archived local sessions.
Archived sessions never appear in the catalog response or UI.
Healthy hosts remain visible when another host fails; an unavailable host
A stored or idle local row creates a Chat mirror with a Codex-only
The first turn omits model/provider overrides on the snapshot fork and pins
Pending and committed supervised bindings use the supervision connection for
Later resumes omit OpenClaw model/provider overrides, preserve Codex's
Disabling supervision or losing the binding/connection lifecycle fails closed
A supervised model-locked Chat cannot be deleted while it protects the native
The Chat mirrors at most 200 user and assistant messages, 512 KiB total, and
The branch flow never resumes the source thread.
The original source remains eligible for both catalogs. The canonical native
Active local sources cannot create a branch or be archived; an existing
Activity-unknown rows can branch without confirmation; archiving requires
A source with an initializing or pending supervised branch cannot be archived
A known active binding owner for the exact target or any non-archived spawned
Confirmed stored or idle local archive removes the row after native success.
Paired-node rows remain visible without Continue or Archive.
Passive listing never subscribes to or answers thread approvals.
Legacy Supervisor config migrates to the canonical Codex config shape.
Legacy list is loaded-only by default, stored enumeration obeys its per-endpoint

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/specs/codex-supervision
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

plugins.entries.codex.config.sessionCatalog.enabled = false

plugins.entries.codex.config.supervision.enabled = true

Codex Desktop -> private stdio App Server -> user Codex home
                                             ^
OpenClaw Codex plugin -> supervision App Server connection
  (defaults to managed user-home stdio; explicit appServer settings are honored)
  -> passive source catalog and read
  -> snapshot pin -> canonical appServer-source branch
  -> visible-history injection and every later supervised Chat turn

Ordinary OpenClaw Codex sessions -> managed agent-home stdio by default
  -> ordinary full harness threads -> OpenClaw Chat and channel delivery

openclaw codex sessions [--search <text>] [--host <id>] [--limit <count>] [--cursor <cursor>] [--json] [gateway-options]
openclaw codex continue <thread-id> [--json] [gateway-options]
openclaw codex archive <thread-id> --confirm-no-other-runner [--json] [gateway-options]

Codex supervision

핵심 요약

Architecture and product boundary for supervising native Codex sessions from OpenClaw.

한국어 가이드 범위: specs/codex-supervision 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Codex supervision
Goal
Product boundary
Ownership
Catalog flow
Operator CLI boundary
Local continuation
Archive behavior
Active thread safety
Paired-node boundary
Permissions
Compatibility
Future work
Acceptance tests

상세 내용

Codex supervision

이 섹션의 세부 항목은 공식 문서 Codex supervision를 참고하세요.

Goal

Product boundary

The catalog registers whenever the Codex plugin is active unless native session discovery is explicitly disabled with:

주요 항목:

List only non-archived Codex threads.
Group local and opted-in paired-node rows by stable host identity.
Create a normal, model-locked Chat branch from a stored or idle Gateway-local
Archive a stored or idle Gateway-local thread only after explicit
Show active local sources without new-branch or archive controls while still
Show the newest rows per host in the main sidebar, keep the full catalog on
Isolate catalog failures by host.

plugins.entries.codex.config.sessionCatalog.enabled = false

plugins.entries.codex.config.supervision.enabled = true

Ownership

The codex plugin owns all Codex App Server behavior:

주요 항목:

endpoint discovery and connection lifecycle
protocol initialization and version checks
thread list, read, resume, archive, and event handling
approval and user-input bridges
native thread bindings to OpenClaw sessions
Codex-only model and harness enforcement after continuation

Codex Desktop -> private stdio App Server -> user Codex home
                                             ^
OpenClaw Codex plugin -> supervision App Server connection
  (defaults to managed user-home stdio; explicit appServer settings are honored)
  -> passive source catalog and read
  -> snapshot pin -> canonical appServer-source branch
  -> visible-history injection and every later supervised Chat turn

Ordinary OpenClaw Codex sessions -> managed agent-home stdio by default
  -> ordinary full harness threads -> OpenClaw Chat and channel delivery

Catalog flow

Operator CLI boundary

The plugin registers three Gateway-backed shell commands:

openclaw codex sessions [--search <text>] [--host <id>] [--limit <count>] [--cursor <cursor>] [--json] [gateway-options]
openclaw codex continue <thread-id> [--json] [gateway-options]
openclaw codex archive <thread-id> --confirm-no-other-runner [--json] [gateway-options]

Local continuation

For a stored or idle Gateway-local row, the UI calls sessions.catalog.continue with catalogId: "codex" plus the host and thread ids. The plugin:

Archive behavior

Active thread safety

주요 항목:

passive catalog clients do not subscribe or auto-deny approvals
rows currently reported active expose neither a new branch nor Archive
an unmapped source becomes a visible-history branch whose canonical harness
notLoaded is shown as activity unknown and can be archived only after
local archive requires that confirmation plus a fresh idle or notLoaded

Paired-node boundary

Permissions

Each computer opts in locally. Enabling the Gateway does not authorize another node to read its Codex metadata. The node capability must pass normal pairing and command-policy approval.

Compatibility

Future work

Archived browsing is not part of the planned supervision sidebar. Native Codex surfaces remain the recovery path for archived threads.

주요 항목:

node-side streaming runner and event bridge for remote continuation
explicit runner and approval-owner leases for simultaneous client handoff
remote archive after a runner-ownership lease or equivalent fencing exists
interrupt and richer active-session observation
audited handoff between Codex Desktop, CLI, and OpenClaw

Acceptance tests

returns no fresh rows instead of inventing an offline session status.

주요 항목:

Enabling supervision lists non-archived local sessions.
Archived sessions never appear in the catalog response or UI.
Healthy hosts remain visible when another host fails; an unavailable host
A stored or idle local row creates a Chat mirror with a Codex-only
The first turn omits model/provider overrides on the snapshot fork and pins
Pending and committed supervised bindings use the supervision connection for
Later resumes omit OpenClaw model/provider overrides, preserve Codex's
Disabling supervision or losing the binding/connection lifecycle fails closed
A supervised model-locked Chat cannot be deleted while it protects the native
The Chat mirrors at most 200 user and assistant messages, 512 KiB total, and
The branch flow never resumes the source thread.
The original source remains eligible for both catalogs. The canonical native
Active local sources cannot create a branch or be archived; an existing
Activity-unknown rows can branch without confirmation; archiving requires
A source with an initializing or pending supervised branch cannot be archived
A known active binding owner for the exact target or any non-archived spawned
Confirmed stored or idle local archive removes the row after native success.
Paired-node rows remain visible without Continue or Archive.
Passive listing never subscribes to or answers thread approvals.
Legacy Supervisor config migrates to the canonical Codex config shape.
Legacy list is loaded-only by default, stored enumeration obeys its per-endpoint

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/specs/codex-supervision
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

plugins.entries.codex.config.sessionCatalog.enabled = false

plugins.entries.codex.config.supervision.enabled = true

Codex Desktop -> private stdio App Server -> user Codex home
                                             ^
OpenClaw Codex plugin -> supervision App Server connection
  (defaults to managed user-home stdio; explicit appServer settings are honored)
  -> passive source catalog and read
  -> snapshot pin -> canonical appServer-source branch
  -> visible-history injection and every later supervised Chat turn

Ordinary OpenClaw Codex sessions -> managed agent-home stdio by default
  -> ordinary full harness threads -> OpenClaw Chat and channel delivery

openclaw codex sessions [--search <text>] [--host <id>] [--limit <count>] [--cursor <cursor>] [--json] [gateway-options]
openclaw codex continue <thread-id> [--json] [gateway-options]
openclaw codex archive <thread-id> --confirm-no-other-runner [--json] [gateway-options]

Codex supervision

핵심 요약

문서 구성

상세 내용

Codex supervision

Goal

Product boundary

Ownership

Catalog flow

Operator CLI boundary

Local continuation

Archive behavior

Active thread safety

Paired-node boundary

Permissions

Compatibility

Future work

Acceptance tests

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Codex supervision

핵심 요약

문서 구성

상세 내용

Codex supervision

Goal

Product boundary

Ownership

Catalog flow

Operator CLI boundary

Local continuation

Archive behavior

Active thread safety

Paired-node boundary

Permissions

Compatibility

Future work

Acceptance tests

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드