Codex harness runtime

Codex harness runtime 문서는 OpenClaw 공식 문서(plugins/codex-harness-runtime)를 한국어로 정리한 가이드입니다. Runtime boundaries, hooks, tools, permissions, and diagnostics for the Codex harness 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Runtime boundaries, hooks, tools, permissions, and diagnostics for the Codex harness

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

문서 구성

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

개요
Thread bindings and model changes
Supervision and safe continuation
Visible replies and heartbeats
Hook boundaries
V1 support contract
Native permissions and MCP elicitations
Queue steering
Codex feedback upload
Compaction and transcript mirror
Media and delivery
관련 문서

상세 내용

본문

Runtime contract for Codex harness turns. For setup and routing, see Codex harness. For config fields, see Codex harness reference.

개요

Codex owns the native model loop, native thread resume, native tool continuation, and native compaction. OpenClaw owns channel routing, session files, visible message delivery, OpenClaw dynamic tools, approvals, media delivery, and a transcript mirror around that boundary.

Thread bindings and model changes

When an OpenClaw session is attached to an existing Codex thread, the next turn resends the currently selected model, approval policy, sandbox, approvals reviewer, and service tier to app-server. Switching from openai/gpt-5.5 to openai/gpt-5.2 keeps the thread binding but asks Codex to continue with the newly selected model.

Supervision and safe continuation

Codex supervision is an opt-in capability of the same codex plugin. It discovers native threads through a separate connection and projects only non-archived sessions into the Gateway catalog. Without explicit appServer connection settings, that connection uses managed user-home stdio while the ordinary harness remains agent-scoped. Listing and metadata reads are passive: they do not resume a thread, subscribe OpenClaw to its live events, or answer its approvals.

Visible replies and heartbeats

Direct/source chat turns through the Codex harness default to automatic final assistant delivery for internal WebChat surfaces, matching the Pi harness contract: the agent replies normally and OpenClaw posts the final text to the source conversation. Set messages.visibleReplies: "message_tool" to keep final assistant text private unless the agent calls message(action="send").

Hook boundaries

OpenClaw does not use project or global Codex hooks.json files to route plugin behavior. For the native tool and permission bridge, OpenClaw injects per-thread Codex config for PreToolUse, PostToolUse, PermissionRequest, and Stop.

Layer	Owner	Purpose
OpenClaw plugin hooks	OpenClaw	Product/plugin compatibility across OpenClaw and Codex harnesses.
Codex app-server extension middleware	OpenClaw bundled plugins	Per-turn adapter behavior around OpenClaw dynamic tools.
Codex native hooks	Codex	Low-level Codex lifecycle and native tool policy from Codex config.

V1 support contract

Surface	Support	Why
OpenAI model loop through Codex	Supported	Codex app-server owns the OpenAI turn, native thread resume, and native tool continuation.
OpenClaw channel routing and delivery	Supported	Telegram, Discord, Slack, WhatsApp, iMessage, and other channels stay outside the model runtime.
OpenClaw dynamic tools	Supported	Codex asks OpenClaw to execute these tools, so OpenClaw stays in the execution path.
Prompt and context plugins	Supported	OpenClaw projects OpenClaw-specific prompt/context into the Codex turn while leaving Codex-owned base, model, and configured project-doc prompts in the native Codex lane. OpenClaw disables Codex's built-in personality for native threads so agent workspace personality files remain authoritative. Native Codex developer instructions accept only command guidance explicitly scoped to `codex_app_server`; legacy global command hints remain for non-Codex prompt surfaces.
Context engine lifecycle	Supported	Assemble, ingest, and after-turn maintenance run around Codex turns. Context engines do not replace native Codex compaction.
Dynamic tool hooks	Supported	`before_tool_call`, `after_tool_call`, and tool-result middleware run around OpenClaw-owned dynamic tools.
Lifecycle hooks	Supported as adapter observations	`llm_input`, `llm_output`, `agent_end`, `before_compaction`, and `after_compaction` fire with honest Codex-mode payloads.
Final-answer revision gate	Supported through native hook relay	Codex `Stop` is relayed to `before_agent_finalize`; `revise` asks Codex for one more model pass before finalization.
Native shell, patch, and MCP block or observe	Supported through native hook relay	Codex `PreToolUse` and `PostToolUse` are relayed for committed native tool surfaces, including MCP payloads on Codex app-server `0.142.0` or newer. Blocking is supported; argument rewriting is not.
Native permission policy	Supported through Codex app-server approvals and compatibility native hook relay	Codex app-server approval requests route through OpenClaw after Codex review. The `PermissionRequest` native hook relay is opt-in for native approval modes because Codex emits it before guardian review.
App-server trajectory capture	Supported	OpenClaw records the request it sent to app-server and the app-server notifications it receives.

Surface	V1 boundary	Future path
Native tool argument mutation	Codex native pre-tool hooks can block, but OpenClaw does not rewrite Codex-native tool arguments.	Requires Codex hook/schema support for replacement tool input.
Editable Codex-native transcript history	Codex owns canonical native thread history. OpenClaw owns a mirror and can project future context, but should not mutate unsupported internals.	Add explicit Codex app-server APIs if native thread surgery is needed.
`tool_result_persist` for Codex-native tool records	That hook transforms OpenClaw-owned transcript writes, not Codex-native tool records.	Could mirror transformed records, but canonical rewrite needs Codex support.
Rich native compaction metadata	OpenClaw can request native compaction, but does not receive a stable kept/dropped list, token delta, completion summary, or summary payload.	Needs richer Codex compaction events.
Compaction intervention	OpenClaw does not let plugins or context engines veto, rewrite, or replace native Codex compaction.	Add Codex pre/post compaction hooks if plugins need to veto or rewrite native compaction.
Byte-for-byte model API request capture	OpenClaw can capture app-server requests and notifications, but Codex core builds the final OpenAI API request internally.	Needs a Codex model-request tracing event or debug API.

Native permissions and MCP elicitations

For PermissionRequest, OpenClaw only returns explicit allow or deny decisions when policy decides. A no-decision result is not an allow: Codex treats it as no hook decision and falls through to its own guardian or user approval path.

Queue steering

Active-run queue steering maps onto Codex app-server turn/steer. With the default messages.queue.mode: "steer", OpenClaw batches steer-mode chat messages for the configured quiet window and sends them as one turn/steer request in arrival order.

Codex feedback upload

When /diagnostics [note] is approved for a session on the native Codex harness, OpenClaw also calls Codex app-server feedback/upload for relevant Codex threads, including logs for each listed thread and spawned Codex subthreads when available.

Compaction and transcript mirror

When the selected model uses the Codex harness, native thread compaction belongs to Codex app-server. OpenClaw does not run preflight compaction for Codex turns, replace Codex compaction with context-engine compaction, or fall back to OpenClaw or public OpenAI summarization when native compaction cannot be started. OpenClaw keeps a transcript mirror for channel history, search, /new, /reset, and future model or harness switching.

Media and delivery

OpenClaw continues to own media delivery and media provider selection. Image, video, music, PDF, TTS, and media understanding use matching provider/model settings such as agents.defaults.mediaModels.image, agents.defaults.mediaModels.video, pdfModel, and tts.

실습 체크리스트

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

Codex harness runtime

핵심 요약

Runtime boundaries, hooks, tools, permissions, and diagnostics for the Codex harness

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

문서 구성

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

개요
Thread bindings and model changes
Supervision and safe continuation
Visible replies and heartbeats
Hook boundaries
V1 support contract
Native permissions and MCP elicitations
Queue steering
Codex feedback upload
Compaction and transcript mirror
Media and delivery
관련 문서

상세 내용

본문

Runtime contract for Codex harness turns. For setup and routing, see Codex harness. For config fields, see Codex harness reference.

개요

Thread bindings and model changes

Supervision and safe continuation

Visible replies and heartbeats

Hook boundaries

Layer	Owner	Purpose
OpenClaw plugin hooks	OpenClaw	Product/plugin compatibility across OpenClaw and Codex harnesses.
Codex app-server extension middleware	OpenClaw bundled plugins	Per-turn adapter behavior around OpenClaw dynamic tools.
Codex native hooks	Codex	Low-level Codex lifecycle and native tool policy from Codex config.

V1 support contract

Surface	Support	Why
OpenAI model loop through Codex	Supported	Codex app-server owns the OpenAI turn, native thread resume, and native tool continuation.
OpenClaw channel routing and delivery	Supported	Telegram, Discord, Slack, WhatsApp, iMessage, and other channels stay outside the model runtime.
OpenClaw dynamic tools	Supported	Codex asks OpenClaw to execute these tools, so OpenClaw stays in the execution path.
Prompt and context plugins	Supported	OpenClaw projects OpenClaw-specific prompt/context into the Codex turn while leaving Codex-owned base, model, and configured project-doc prompts in the native Codex lane. OpenClaw disables Codex's built-in personality for native threads so agent workspace personality files remain authoritative. Native Codex developer instructions accept only command guidance explicitly scoped to `codex_app_server`; legacy global command hints remain for non-Codex prompt surfaces.
Context engine lifecycle	Supported	Assemble, ingest, and after-turn maintenance run around Codex turns. Context engines do not replace native Codex compaction.
Dynamic tool hooks	Supported	`before_tool_call`, `after_tool_call`, and tool-result middleware run around OpenClaw-owned dynamic tools.
Lifecycle hooks	Supported as adapter observations	`llm_input`, `llm_output`, `agent_end`, `before_compaction`, and `after_compaction` fire with honest Codex-mode payloads.
Final-answer revision gate	Supported through native hook relay	Codex `Stop` is relayed to `before_agent_finalize`; `revise` asks Codex for one more model pass before finalization.
Native shell, patch, and MCP block or observe	Supported through native hook relay	Codex `PreToolUse` and `PostToolUse` are relayed for committed native tool surfaces, including MCP payloads on Codex app-server `0.142.0` or newer. Blocking is supported; argument rewriting is not.
Native permission policy	Supported through Codex app-server approvals and compatibility native hook relay	Codex app-server approval requests route through OpenClaw after Codex review. The `PermissionRequest` native hook relay is opt-in for native approval modes because Codex emits it before guardian review.
App-server trajectory capture	Supported	OpenClaw records the request it sent to app-server and the app-server notifications it receives.

Surface	V1 boundary	Future path
Native tool argument mutation	Codex native pre-tool hooks can block, but OpenClaw does not rewrite Codex-native tool arguments.	Requires Codex hook/schema support for replacement tool input.
Editable Codex-native transcript history	Codex owns canonical native thread history. OpenClaw owns a mirror and can project future context, but should not mutate unsupported internals.	Add explicit Codex app-server APIs if native thread surgery is needed.
`tool_result_persist` for Codex-native tool records	That hook transforms OpenClaw-owned transcript writes, not Codex-native tool records.	Could mirror transformed records, but canonical rewrite needs Codex support.
Rich native compaction metadata	OpenClaw can request native compaction, but does not receive a stable kept/dropped list, token delta, completion summary, or summary payload.	Needs richer Codex compaction events.
Compaction intervention	OpenClaw does not let plugins or context engines veto, rewrite, or replace native Codex compaction.	Add Codex pre/post compaction hooks if plugins need to veto or rewrite native compaction.
Byte-for-byte model API request capture	OpenClaw can capture app-server requests and notifications, but Codex core builds the final OpenAI API request internally.	Needs a Codex model-request tracing event or debug API.

Native permissions and MCP elicitations

Queue steering

Codex feedback upload

Compaction and transcript mirror

Media and delivery

실습 체크리스트

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

Codex harness runtime

핵심 요약

문서 구성

상세 내용

본문

개요

Thread bindings and model changes

Supervision and safe continuation

Visible replies and heartbeats

Hook boundaries

V1 support contract

Native permissions and MCP elicitations

Queue steering

Codex feedback upload

Compaction and transcript mirror

Media and delivery

관련 문서

실습 체크리스트

관련 링크

관련 가이드

Codex harness runtime

핵심 요약

문서 구성

상세 내용

본문

개요

Thread bindings and model changes

Supervision and safe continuation

Visible replies and heartbeats

Hook boundaries

V1 support contract

Native permissions and MCP elicitations

Queue steering

Codex feedback upload

Compaction and transcript mirror

Media and delivery

관련 문서

실습 체크리스트

관련 링크

관련 가이드