Codex harness reference

기준일: 2026-07-26
공식 기준: Codex harness reference

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

핵심 요약

Configuration, auth, discovery, and app-server reference for the Codex harness

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

문서 구성

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

• Plugin config surface
• Supervision
• App-server transport
• Approval and sandbox modes
• Sandboxed native execution
• Auth and environment isolation
• Dynamic tools
• Timeouts
• Model discovery
• Workspace bootstrap files
• Environment overrides
• 관련 문서

상세 내용

본문

This reference covers detailed configuration for the official codex plugin. For setup and routing decisions, start with Codex harness.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Plugin config surface

All Codex harness settings live under plugins.entries.codex.config.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Field	Default	Meaning
discovery	enabled	Model discovery settings for Codex app-server model/list.
appServer	managed stdio app-server	Transport, command, auth, approval, sandbox, and timeout settings. The ordinary harness defaults to agent-scoped state.
codexDynamicToolsLoading	"searchable"	Use "direct" to put OpenClaw dynamic tools directly in the initial Codex tool context.
codexDynamicToolsExclude	[]	Additional OpenClaw dynamic tool names to omit from Codex app-server turns.
codexPlugins	disabled	Native Codex plugin/app support, including opt-in access to connected account apps. See Native Codex plugins.
computerUse	disabled	Codex Computer Use setup. See Codex Computer Use.
sessionCatalog	enabled	Native Codex session discovery for the sidebar. Set enabled: false to disable discovery without disabling the provider or harness.
supervision	disabled	Agent-facing native-session transcript and write-control policy. See Codex supervision.

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 2500,
          },
          appServer: {
            mode: "guardian",
          },
        },
      },
    },
  },
}

Supervision

Native session discovery lists non-archived Codex sessions from the Gateway computer and opted-in paired nodes by default. Disable only that catalog with:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Field	Default	Meaning
enabled	false	Enable agent-facing Codex supervision tools. This does not control the authenticated operator session catalog.
endpoints	built-in local endpoint	Compatibility and advanced endpoint targets for the retained Codex supervision agent and standalone MCP tools. The human catalog and branch flow ignore these targets and use the supervision App Server resolved from appServer.
allowRawTranscripts	false	With supervision enabled, allow autonomous agent or standalone MCP transcript reads and transcript-derived list fields. codex_threads metadata-only reads remain available. Does not control authenticated Control UI continuation.
allowWriteControls	false	With supervision enabled, allow autonomous codex_threads fork, rename, archive, and unarchive mutations plus standalone MCP send, steer, and interrupt operations. Does not bypass other binding, host, status, or confirmation checks.

Field	Applies to	Meaning
id	all	Stable endpoint id.
label	all	Optional display label.
transport	all	"stdio-proxy" or "websocket".
command	stdio-proxy	Optional App Server command.
args	stdio-proxy	Optional command arguments.
cwd	stdio-proxy	Optional child-process working directory.
url	websocket	Required WebSocket or supported local socket URL.
authTokenEnv	websocket	Optional environment variable whose value authenticates the endpoint.

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          sessionCatalog: {
            enabled: false,
          },
        },
      },
    },
  },
}

App-server transport

For ordinary harness turns, OpenClaw starts the managed Codex binary shipped with the official plugin (currently @openai/codex 0.145.0):

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Field	Default	Meaning
transport	"stdio"	"stdio" spawns Codex; explicit "unix" connects to the local control socket; "websocket" connects to url.
homeScope	"agent"	"agent" isolates ordinary harness state per OpenClaw agent. "user" is an explicit opt-in that shares the native $CODEX_HOME or ~/.codex, uses native auth, and enables owner-only thread management. User scope supports local stdio or Unix transport. For the separate supervision connection, an unset value resolves to "user" for stdio or Unix and "agent" for WebSocket.
command	managed Codex binary	Executable for stdio transport. Leave unset to use the managed binary.
args	["app-server", "--listen", "stdio://"]	Arguments for stdio transport.
url	unset	WebSocket App Server URL or unix:// URL. An empty explicit Unix path selects the canonical user-home control socket.
authToken	unset	Bearer token for WebSocket transport. Accepts a literal string or SecretInput such as ${CODEX_APP_SERVER_TOKEN}.
headers	{}	Extra WebSocket headers. Header values accept literal strings or SecretInput values, for example x-codex-client-session-token: "${CODEX_CLIENT_SESSION_TOKEN}".
clearEnv	[]	Extra environment variable names removed from the spawned stdio app-server process after OpenClaw builds its inherited environment.
remoteWorkspaceRoot	unset	Remote Codex app-server workspace root. When set, OpenClaw infers the local workspace root from the resolved OpenClaw workspace, preserves the current cwd suffix under this remote root, and sends only the final app-server cwd to Codex. If the cwd is outside the resolved OpenClaw workspace root, OpenClaw fails closed instead of sending a gateway-local path to the remote app-server.
loopDetectionPreToolUseRelay	true	Install the Codex PreToolUse subprocess used only for OpenClaw loop detection and its explicit no-policy marker. Set false to reduce per-tool process fan-out. Before-tool plugin hooks and trusted-tool policy still install their required relay.
requestTimeoutMs	60000	Timeout for app-server control-plane calls.
turnCompletionIdleTimeoutMs	60000	Quiet window after Codex accepts a turn or after a turn-scoped app-server request while OpenClaw waits for turn/completed.
turnAssistantCompletionIdleTimeoutMs	10000	Quiet window after a final/non-commentary assistant item or pre-tool raw assistant completion arms the assistant-output release while OpenClaw still waits for turn/completed. Raising it gives Codex more time to emit turn/completed before OpenClaw interrupts and releases the session lane.
postToolRawAssistantCompletionIdleTimeoutMs	300000	Completion-idle and progress guard used after a tool handoff, native tool completion, post-tool raw assistant progress, raw reasoning completion, or reasoning progress while OpenClaw waits for turn/completed. Use this for trusted or heavy workloads where post-tool synthesis can legitimately stay quiet longer than the final assistant release budget.
mode	"yolo" unless local Codex requirements disallow YOLO	Preset for YOLO or guardian-reviewed execution.
approvalPolicy	"never" or an allowed guardian approval policy	Native Codex approval policy sent to thread start, resume, and turn.
sandbox	"danger-full-access" or an allowed guardian sandbox	Native Codex sandbox mode sent to thread start and resume. Active OpenClaw sandboxes narrow danger-full-access turns to Codex workspace-write; the turn network flag follows OpenClaw sandbox egress.
approvalsReviewer	"user" or an allowed guardian reviewer	Use "auto_review" to let Codex review native approval prompts when allowed.
defaultWorkspaceDir	current process directory	Workspace used by /codex bind when --cwd is omitted.
serviceTier	unset	Optional Codex app-server service tier. "priority" enables fast-mode routing, "flex" requests flex processing, and null clears the override. Legacy "fast" is accepted as "priority".
networkProxy	disabled	Opt into Codex permissions-profile networking for app-server commands. OpenClaw defines the selected permissions.<profile>.network config and selects it with default_permissions instead of sending sandbox.
experimental.sandboxExecServer	false	Preview opt-in that registers an OpenClaw sandbox-backed Codex environment with the supported Codex app-server so native Codex execution can run inside the active OpenClaw sandbox.

codex app-server --listen stdio://

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://gateway-host:39175",
            authToken: "${CODEX_APP_SERVER_TOKEN}",
            requestTimeoutMs: 60000,
          },
        },
      },
    },
  },
}

plugins: {
    entries: {
      codex: {
        config: {
          appServer: {
            sandbox: "workspace-write",
            networkProxy: {
              enabled: true,
              domains: {
                "api.openai.com": "allow",
                "blocked.example.com": "deny",
              },
              allowUpstreamProxy: true,
              proxyUrl: "http://127.0.0.1:3128",
            },
          },
        },
      },
    },
  },
};

Approval and sandbox modes

Local stdio app-server sessions default to YOLO mode: approvalPolicy: "never", approvalsReviewer: "user", and sandbox: "danger-full-access". This trusted local operator posture lets unattended OpenClaw turns and heartbeats make progress without native approval prompts that nobody is around to answer.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            serviceTier: "priority",
          },
        },
      },
    },
  },
}

Sandboxed native execution

The stable default is fail-closed: active OpenClaw sandboxing disables native Codex execution surfaces that would otherwise run from the Codex app-server host. Use appServer.experimental.sandboxExecServer: true only when you want to try Codex's remote environment support with OpenClaw's sandbox backend. This preview path works with every supported Codex app-server version.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            experimental: {
              sandboxExecServer: true,
            },
          },
        },
      },
    },
  },
}

Auth and environment isolation

In the default per-agent home, auth is selected in this order:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw migrate codex --dry-run
openclaw migrate apply codex --yes

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],
          },
        },
      },
    },
  },
}

Dynamic tools

Codex dynamic tools default to searchable loading, exposed under the openclaw namespace with deferLoading: true. OpenClaw normally does not expose dynamic tools that duplicate Codex-native workspace operations or Codex's own tool-search surface:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• read
• write
• edit
• apply_patch
• exec
• process
• update_plan
• tool_call
• tool_describe
• tool_search
• tool_search_code

Timeouts

OpenClaw-owned dynamic tool calls are bounded independently from appServer.requestTimeoutMs. Each Codex item/tool/call request uses the first available timeout in this order:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• A positive per-call timeoutMs argument.
• For image_generate, agents.defaults.mediaModels.image.timeoutMs.
• For image_generate without a configured timeout, the 120 second
• For the media-understanding image tool, the selected image-capable tools.media.models[] entry's timeoutSeconds
• For the message tool, a fixed 600 second outer budget that covers Gateway delivery and bounded same-key reconciliation.
• The 90 second dynamic-tool default.

Model discovery

By default, the Codex plugin asks the app-server for available models. Model availability is owned by Codex app-server, so the list can change when OpenClaw upgrades the bundled @openai/codex version or when a deployment points appServer.command at a different Codex binary. Availability can also be account-scoped. Use /codex models on a running gateway to see the live catalog for that harness and account.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Model id	Display name	Reasoning efforts
gpt-5.5	gpt-5.5	low, medium, high, xhigh
gpt-5.4-mini	GPT-5.4-Mini	low, medium, high, xhigh

Model id	Input modalities	Reasoning efforts
gpt-5.6-sol	text, image	low, medium, high, xhigh, max, ultra
gpt-5.6-terra	text, image	low, medium, high, xhigh, max, ultra
gpt-5.6-luna	text, image	low, medium, high, xhigh, max
gpt-5.5	text, image	low, medium, high, xhigh
gpt-5.2	text, image	low, medium, high, xhigh

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 2500,
          },
        },
      },
    },
  },
}

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: false,
          },
        },
      },
    },
  },
}

Workspace bootstrap files

Codex handles AGENTS.md itself through native project-doc discovery. OpenClaw does not write synthetic Codex project-doc files or depend on Codex fallback filenames for persona files, because Codex fallbacks only apply when AGENTS.md is missing.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• TOOLS.md is forwarded as inherited Codex developer instructions, so
• SOUL.md, IDENTITY.md, and USER.md are forwarded as turn-scoped
• The compact loaded OpenClaw skills list is also forwarded as turn-scoped
• HEARTBEAT.md content is not injected; heartbeat turns get a
• MEMORY.md content from the configured agent workspace is not pasted into
• BOOTSTRAP.md, when present, is forwarded as OpenClaw turn input reference

Environment overrides

Environment overrides remain available for local testing:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• OPENCLAW_CODEX_APP_SERVER_BIN
• OPENCLAW_CODEX_APP_SERVER_ARGS
• OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
• OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
• OPENCLAW_CODEX_APP_SERVER_SANDBOX

관련 문서

주요 항목:

• Codex harness
• Codex harness runtime
• Codex supervision
• Native Codex plugins
• Codex Computer Use
• OpenAI provider
• Configuration reference

실습 체크리스트

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

자주 쓰는 명령·설정 예시

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 2500,
          },
          appServer: {
            mode: "guardian",
          },
        },
      },
    },
  },
}

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          sessionCatalog: {
            enabled: false,
          },
        },
      },
    },
  },
}

codex app-server --listen stdio://

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://gateway-host:39175",
            authToken: "${CODEX_APP_SERVER_TOKEN}",
            requestTimeoutMs: 60000,
          },
        },
      },
    },
  },
}

plugins: {
    entries: {
      codex: {
        config: {
          appServer: {
            sandbox: "workspace-write",
            networkProxy: {
              enabled: true,
              domains: {
                "api.openai.com": "allow",
                "blocked.example.com": "deny",
              },
              allowUpstreamProxy: true,
              proxyUrl: "http://127.0.0.1:3128",
            },
          },
        },
      },
    },
  },
};

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            serviceTier: "priority",
          },
        },
      },
    },
  },
}

관련 링크

• 공식 원문: plugins/codex-harness-reference
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.