diff --git a/.agents/skills/openclaw-docs/SKILL.md b/.agents/skills/openclaw-docs/SKILL.md new file mode 100644 index 00000000000..10f8225e329 --- /dev/null +++ b/.agents/skills/openclaw-docs/SKILL.md @@ -0,0 +1,234 @@ +--- +name: openclaw-docs +description: Write or review high-quality OpenClaw developer documentation. +dependencies: [] +--- + +# OpenClaw Docs + +## Overview + +Use this skill when writing, editing, or reviewing OpenClaw developer documentation for APIs, SDKs, CLI tools, integrations, quickstarts, platform guides, or technical product docs. + +Write documentation that is concise, helpful, and comprehensive: fast for first success, precise for production, and easy to scan when debugging. + +## Core Model + +Use an OpenClaw documentation model, strengthened by Write the Docs principles: + +- Lead with what the developer is trying to do. +- Give one recommended path before alternatives. +- Make examples runnable and realistic. +- Keep guides task-oriented and references exhaustive. +- Explain production risks exactly where developers can make mistakes. +- Link concepts, guides, API references, SDKs, testing, and troubleshooting so readers can move between them without rereading. +- Treat docs as part of the product lifecycle: draft them before or alongside implementation, review them with code, and keep them current. +- Make each page discoverable, addressable, cumulative, complete within its stated scope, and easy to skim. + +## Structure + +Choose the page type before writing: + +- Overview: route readers to the right product, integration path, or guide. +- Quickstart: get a new user to a working result with the fewest safe steps. +- Topic page: give an end-to-end overview of a major domain entity, with setup, + key subtopics, troubleshooting, and links to deeper references. +- Guide: explain one workflow from prerequisites to production readiness. +- API reference: define every object, endpoint, parameter, enum, response, error, and version rule. +- SDK or CLI reference: document install, auth, commands or methods, options, examples, and failure modes. +- Testing guide: show sandbox setup, fixtures, test data, simulated failures, and live-mode differences. +- Troubleshooting guide: map symptoms to checks, causes, and fixes. + +Use this default topic page structure: + +1. Title: name the major entity or surface. +2. Overview: explain what it is, what it owns, and what it does not own. +3. Requirements: include only when setup needs specific accounts, versions, + permissions, plugins, operating systems, or credentials. +4. Quickstart: show the recommended setup path and smallest reliable verification. +5. Configuration: show the minimum configuration needed to use the surface, + common variants users must choose between, and where each option is set: + CLI, config file, environment variable, plugin manifest, dashboard, or API. +6. Subtopics: organize the entity's major concepts, workflows, and decisions by + reader intent. +7. Troubleshooting: diagnose common observable failures. +8. Related: link to guides, references, commands, concepts, and adjacent topics. + +Topic pages may be longer than quickstarts, but they should not become exhaustive +references. Move field tables, API contracts, narrow internals, legacy details, +and rare debugging workflows to linked reference or troubleshooting pages when +they interrupt the end-to-end overview. + +For configuration, keep task-critical options inline. Link to reference docs for +full option lists, defaults, enums, generated schemas, and advanced settings. Do +not duplicate exhaustive config reference tables in topic pages unless the topic +page is itself the reference. + +Use this default guide structure: + +1. Title: name the outcome, not the implementation detail. +2. Opening: state what the reader can accomplish in one or two sentences. +3. Before you begin: list accounts, keys, permissions, versions, tools, and assumptions. +4. Choose a path: compare options only when the reader must decide. +5. Steps: use verb-led headings with code, expected output, and checks. +6. Test: show the smallest reliable proof that the integration works. +7. Production readiness: cover security, idempotency, retries, limits, observability, migrations, and cleanup. +8. Troubleshooting: include common errors near the workflow that causes them. +9. See also: link to concepts, API references, SDK docs, and adjacent guides. + +Keep navigation user-intent based. Do not force readers to understand internal product taxonomy before they can pick a task. + +## Documentation Lifecycle + +Write and maintain docs with the same discipline as code: + +- Draft docs early enough to expose unclear product, API, CLI, or config design. +- Keep docs source near the code, config, command, plugin, or protocol it describes when the repo layout allows it. +- Avoid duplicate truth. If the same contract appears in multiple places, pick the canonical page and link to it. +- Update docs in the same change as behavior, config, API, CLI, plugin, or troubleshooting changes. +- Remove, redirect, or clearly mark stale docs. Incorrect docs are worse than missing docs. +- Involve the right reviewers: code owners for behavior, support or QA for user failure modes, and docs maintainers for structure and style. +- Preserve older-version guidance only when users need it; otherwise document the current supported behavior. + +Do not use FAQs as a dumping ground for unrelated material. Promote recurring questions into task, concept, troubleshooting, or reference pages. + +## Writing Style + +Write in a direct, practical voice: + +- Use present tense and active voice. +- Address the reader as "you" when giving instructions. +- Prefer short paragraphs and scannable lists. +- Use concrete nouns: "agent profile", "Gateway webhook", "plugin manifest", "session state". +- Put caveats exactly where they affect the step. +- Avoid marketing language, hype, generic benefits, and vague claims. +- Avoid long conceptual lead-ins before the first actionable step. +- Do not over-explain common developer concepts unless the product has a nonstandard contract. +- Define OpenClaw-specific jargon and abbreviations before first use. +- Use sentence case for headings unless an OpenClaw product name, command, or identifier requires capitalization. +- Use descriptive link text that names the destination or action; avoid vague links such as "this page" or "click here". +- Avoid culturally specific idioms, violent idioms, and jokes that make docs harder to translate or scan. +- Write accessible prose: do not rely on color, screenshots, or visual position as the only way to understand an instruction. + +Use headings that describe actions or reference surfaces: + +- Good: "Create an agent", "Configure a Slack channel", "Repair plugin installation" +- Avoid: "How it works", "Under the hood", "Important notes" unless the section truly needs that shape + +Use precise modal language: + +- Use "must" for required behavior. +- Use "can" for optional capability. +- Use "recommended" for the default path. +- Use "avoid" for known footguns. +- Explain "why" only when it changes a developer decision. + +## Detail Level + +Vary detail by page type: + +- Overview pages: be brief; help readers choose. +- Quickstarts: be procedural; include only what is needed for first success. +- Guides: be complete for one workflow; include decisions, side effects, and failure handling. +- References: be exhaustive; document every field, default, enum, nullable value, constraint, response, and error. +- Troubleshooting: be explicit; assume the reader is blocked and needs observable checks. + +Go deep where mistakes are expensive: + +- Authentication and secret handling +- Money movement, billing, permissions, and irreversible actions +- Webhooks, retries, duplicate events, and ordering +- Idempotency and concurrency +- Sandbox versus production differences +- Versioning, migrations, and backwards compatibility +- Limits, rate limits, quotas, and timeouts +- Error codes and recovery paths +- Data retention, privacy, and compliance-sensitive behavior + +Do not bury this detail in a distant reference if developers need it to complete the task safely. + +## Examples + +Make examples production-shaped, even when using test data: + +- Prefer complete copy-pasteable commands or snippets. +- Use realistic variable names and values. +- Mark placeholders clearly with angle-bracket names such as `` or ``. +- Show expected success output after commands. +- Show full request and response examples for API references when response shape matters. +- Keep one conceptual unit per code block. +- Use language-specific code fences. +- Avoid toy examples that hide required setup, auth, error handling, or cleanup. + +When multiple languages are useful, keep the same scenario across languages so readers can compare equivalents. + +## Discoverability and Navigation + +Design every page so readers can find it, link to it, and decide quickly whether it answers their question: + +- Use goal-oriented titles and headings that match likely search terms. +- Start each page with a concise answer to "what can I do here?" +- Include metadata or frontmatter required by the OpenClaw docs index. +- Add "Read when" hints for docs-list routing when creating or changing OpenClaw docs pages that participate in the docs index. +- Link from likely entry points, not only from nearby internal taxonomy pages. +- Keep section headings stable enough for links from issues, PRs, support replies, and chat answers. +- Order tutorials and examples from prerequisites to advanced tasks; order reference pages alphabetically or topically when that helps lookup. +- State scope up front when a page is intentionally partial. + +## API Reference Pattern + +For endpoints, methods, objects, or commands, include: + +1. Short purpose statement. +2. Auth or permission requirements. +3. Request shape, including path, query, headers, and body fields. +4. Parameter table with type, requiredness, default, constraints, enum values, and side effects. +5. Return shape with object lifecycle states. +6. Error cases with codes, causes, and recovery guidance. +7. Runnable example request. +8. Representative successful response. +9. Related guides and adjacent reference pages. + +For nested objects, document child fields near their parent. Do not make readers jump across pages to understand the shape of a single request. + +## Verification + +Verify docs changes like product changes: + +- Run the relevant docs build, docs index, formatter, link checker, or generated-doc check when available. +- Run commands, snippets, and examples that the page tells users to run whenever feasible. +- Confirm screenshots, UI labels, CLI output, config keys, flags, defaults, errors, and file paths match current behavior. +- Prefer executable checks over prose-only review for API, CLI, config, generated reference, and troubleshooting docs. +- If a verification step is not feasible, say what was not verified and why. + +## Completeness Checks + +Before finalizing a page, verify: + +- The first screen tells readers what they can accomplish. +- The recommended path is obvious. +- Prerequisites are explicit and testable. +- Examples can run with documented inputs. +- The page has a clear audience: user, operator, plugin author, contributor, or maintainer. +- Test-mode and production-mode behavior are separated. +- Security-sensitive values are never exposed in examples. +- Every warning is attached to the step where it matters. +- Edge cases are documented where they affect implementation. +- API fields include types, defaults, constraints, and errors. +- Troubleshooting starts from observable symptoms. +- Related links help the reader continue without duplicating the page. +- The page says where to get support, file issues, or contribute when that is relevant to the reader's next step. +- The page is complete for the scope it claims, or the limitation is stated up front. + +## Review Pass + +Edit in this order: + +1. Remove repetition and generic explanation. +2. Move conceptual background below the first useful action unless it is required to choose correctly. +3. Replace passive or abstract wording with concrete instructions. +4. Tighten headings until the outline reads like a task map. +5. Add missing operational details for production safety. +6. Check examples for copy-paste accuracy. +7. Add links between guide, reference, SDK, testing, and troubleshooting surfaces. +8. Check discoverability, addressability, accessibility, and docs-as-code verification. diff --git a/.gitignore b/.gitignore index f322f52f917..1c3d3cf5888 100644 --- a/.gitignore +++ b/.gitignore @@ -117,6 +117,7 @@ USER.md !.agents/skills/crabbox/** !.agents/skills/gitcrawl/ !.agents/skills/gitcrawl/** +!.agents/skills/openclaw-docs/** !.agents/skills/openclaw-ghsa-maintainer/ !.agents/skills/openclaw-ghsa-maintainer/** !.agents/skills/openclaw-parallels-smoke/ diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index d968ed7a847..0d663766feb 100644 --- a/docs/.i18n/glossary.zh-CN.json +++ b/docs/.i18n/glossary.zh-CN.json @@ -111,6 +111,26 @@ "source": "Codex harness", "target": "Codex harness" }, + { + "source": "Codex harness reference", + "target": "Codex harness reference" + }, + { + "source": "Codex harness runtime", + "target": "Codex harness runtime" + }, + { + "source": "Native Codex plugins", + "target": "Native Codex plugins" + }, + { + "source": "Codex Computer Use", + "target": "Codex Computer Use" + }, + { + "source": "Diagnostics export", + "target": "诊断导出" + }, { "source": "Agent harness plugins", "target": "Agent harness plugins" @@ -691,6 +711,10 @@ "source": "Migrate", "target": "迁移" }, + { + "source": "Migrate CLI", + "target": "迁移 CLI" + }, { "source": "Migrating", "target": "迁移" @@ -783,6 +807,10 @@ "source": "Rich Output Protocol", "target": "富输出协议" }, + { + "source": "Trajectory export", + "target": "轨迹导出" + }, { "source": "Tencent Cloud (TokenHub)", "target": "腾讯云（TokenHub）" diff --git a/docs/concepts/agent-runtimes.md b/docs/concepts/agent-runtimes.md index ddf06730fda..dbeb9e9028a 100644 --- a/docs/concepts/agent-runtimes.md +++ b/docs/concepts/agent-runtimes.md @@ -109,7 +109,7 @@ This is the agent-facing decision tree: For the OpenAI-family prefix split, see [OpenAI](/providers/openai) and [Model providers](/concepts/model-providers). For the Codex runtime support -contract, see [Codex harness](/plugins/codex-harness#v1-support-contract). +contract, see [Codex harness runtime](/plugins/codex-harness-runtime#v1-support-contract). ## Runtime ownership @@ -207,7 +207,7 @@ Use this shape for runtime docs: | What is intentionally unsupported? | Users should not assume PI equivalence where the native runtime owns more state. | The Codex runtime support contract is documented in -[Codex harness](/plugins/codex-harness#v1-support-contract). +[Codex harness runtime](/plugins/codex-harness-runtime#v1-support-contract). ## Status labels @@ -224,6 +224,7 @@ runtime policy first. Legacy session runtime pins no longer decide routing. ## Related - [Codex harness](/plugins/codex-harness) +- [Codex harness runtime](/plugins/codex-harness-runtime) - [OpenAI](/providers/openai) - [Agent harness plugins](/plugins/sdk-agent-harness) - [Agent loop](/concepts/agent-loop) diff --git a/docs/docs.json b/docs/docs.json index d33d3f4fd51..44933712b4e 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1707,6 +1707,14 @@ "reference/device-models" ] }, + { + "group": "Codex harness", + "pages": [ + "plugins/codex-harness-reference", + "plugins/codex-harness-runtime", + "plugins/codex-native-plugins" + ] + }, { "group": "Templates", "pages": [ diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index e55592ba5ba..c1557273f6f 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -217,8 +217,9 @@ See [MCP](/cli/mcp#openclaw-as-an-mcp-client-registry) and ### Codex harness plugin config The bundled `codex` plugin owns native Codex app-server harness settings under -`plugins.entries.codex.config`. See [Codex harness](/plugins/codex-harness) for -the full runtime model. +`plugins.entries.codex.config`. See +[Codex harness reference](/plugins/codex-harness-reference) for the full config +surface and [Codex harness](/plugins/codex-harness) for the runtime model. `codexPlugins` applies only to sessions that select the native Codex harness. It does not enable Codex plugins for Pi, normal OpenAI provider runs, ACP diff --git a/docs/gateway/diagnostics.md b/docs/gateway/diagnostics.md index 5877cc9c6e3..8c5234d5c02 100644 --- a/docs/gateway/diagnostics.md +++ b/docs/gateway/diagnostics.md @@ -69,7 +69,7 @@ That makes the common Codex debugging loop short: notice the bad behavior in Telegram, Discord, or another channel, run `/diagnostics`, approve once, share the report with support, then run the printed `codex resume ` command locally if you want to inspect the native Codex thread yourself. See -[Codex harness](/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) for +[Codex harness](/plugins/codex-harness#inspect-codex-threads-locally) for that inspection workflow. ## What the export contains diff --git a/docs/plugins/codex-harness-reference.md b/docs/plugins/codex-harness-reference.md new file mode 100644 index 00000000000..354a584d338 --- /dev/null +++ b/docs/plugins/codex-harness-reference.md @@ -0,0 +1,376 @@ +--- +summary: "Configuration, auth, discovery, and app-server reference for the Codex harness" +title: "Codex harness reference" +read_when: + - You need every Codex harness config field + - You are changing app-server transport, auth, discovery, or timeout behavior + - You are debugging Codex harness startup, model discovery, or environment isolation +--- + +This reference covers the detailed configuration for the bundled `codex` +plugin. For setup and routing decisions, start with +[Codex harness](/plugins/codex-harness). + +## Plugin config surface + +All Codex harness settings live under `plugins.entries.codex.config`. + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + discovery: { + enabled: true, + timeoutMs: 2500, + }, + appServer: { + mode: "guardian", + }, + }, + }, + }, + }, +} +``` + +Supported top-level fields: + +| 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. | +| `codexDynamicToolsProfile` | `"native-first"` | Use `"openclaw-compat"` to expose the full OpenClaw dynamic tool set to Codex app-server. | +| `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 for migrated source-installed curated plugins. See [Native Codex plugins](/plugins/codex-native-plugins). | +| `computerUse` | disabled | Codex Computer Use setup. See [Codex Computer Use](/plugins/codex-computer-use). | + +## App-server transport + +By default, OpenClaw starts the managed Codex binary shipped with the bundled +plugin: + +```bash +codex app-server --listen stdio:// +``` + +This keeps the app-server version tied to the bundled `codex` plugin instead of +whichever separate Codex CLI happens to be installed locally. Set +`appServer.command` only when you intentionally want to run a different +executable. + +For an already-running app-server, use WebSocket transport: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + appServer: { + transport: "websocket", + url: "ws://gateway-host:39175", + authToken: "${CODEX_APP_SERVER_TOKEN}", + requestTimeoutMs: 60000, + }, + }, + }, + }, + }, +} +``` + +Supported `appServer` fields: + +| Field | Default | Meaning | +| ----------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` spawns Codex; `"websocket"` connects to `url`. | +| `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. | +| `authToken` | unset | Bearer token for WebSocket transport. | +| `headers` | `{}` | Extra WebSocket headers. | +| `clearEnv` | `[]` | Extra environment variable names removed from the spawned stdio app-server process after OpenClaw builds its inherited environment. | +| `requestTimeoutMs` | `60000` | Timeout for app-server control-plane calls. | +| `turnCompletionIdleTimeoutMs` | `60000` | Quiet window after a turn-scoped app-server request while OpenClaw waits for `turn/completed`. | +| `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. | +| `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"`. | + +The plugin blocks older or unversioned app-server handshakes. Codex app-server +must report stable version `0.125.0` or newer. + +## 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. + +If Codex's local system requirements file disallows implicit YOLO approval, +reviewer, or sandbox values, OpenClaw treats the implicit default as guardian +instead and selects allowed guardian permissions. Hostname-matching +`[[remote_sandbox_config]]` entries in the same requirements file are honored +for the sandbox default decision. + +Set `appServer.mode: "guardian"` for Codex guardian-reviewed approvals: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + appServer: { + mode: "guardian", + serviceTier: "priority", + }, + }, + }, + }, + }, +} +``` + +The `guardian` preset expands to `approvalPolicy: "on-request"`, +`approvalsReviewer: "auto_review"`, and `sandbox: "workspace-write"` when those +values are allowed. Individual policy fields override `mode`. The older +`guardian_subagent` reviewer value is still accepted as a compatibility alias, +but new configs should use `auto_review`. + +## Auth and environment isolation + +Auth is selected in this order: + +1. An explicit OpenClaw Codex auth profile for the agent. +2. The app-server's existing account in that agent's Codex home. +3. For local stdio app-server launches only, `CODEX_API_KEY`, then + `OPENAI_API_KEY`, when no app-server account is present and OpenAI auth is + still required. + +When OpenClaw sees a ChatGPT subscription-style Codex auth profile, it removes +`CODEX_API_KEY` and `OPENAI_API_KEY` from the spawned Codex child process. That +keeps Gateway-level API keys available for embeddings or direct OpenAI models +without making native Codex app-server turns bill through the API by accident. + +Explicit Codex API-key profiles and local stdio env-key fallback use app-server +login instead of inherited child-process env. WebSocket app-server connections +do not receive Gateway env API-key fallback; use an explicit auth profile or the +remote app-server's own account. + +Stdio app-server launches inherit OpenClaw's process environment by default, but +OpenClaw owns the Codex app-server account bridge and sets both `CODEX_HOME` and +`HOME` to per-agent directories under that agent's OpenClaw state. Codex's own +skill loader reads `$CODEX_HOME/skills` and `$HOME/.agents/skills`, so both +values are isolated for local app-server launches. That keeps Codex-native +skills, plugins, config, accounts, and thread state scoped to the OpenClaw agent +instead of leaking in from the operator's personal Codex CLI home. + +OpenClaw plugins and OpenClaw skill snapshots still flow through OpenClaw's own +plugin registry and skill loader. Personal Codex CLI assets do not. If you have +useful Codex CLI skills or plugins that should become part of an OpenClaw agent, +inventory them explicitly: + +```bash +openclaw migrate codex --dry-run +openclaw migrate apply codex --yes +``` + +If a deployment needs additional environment isolation, add those variables to +`appServer.clearEnv`: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + appServer: { + clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"], + }, + }, + }, + }, + }, +} +``` + +`appServer.clearEnv` only affects the spawned Codex app-server child process. +`CODEX_HOME` and `HOME` remain reserved for OpenClaw's per-agent Codex +isolation on local launches. + +## Dynamic tools + +Codex dynamic tools default to the `native-first` profile and `searchable` +loading. In that mode, OpenClaw does not expose dynamic tools that duplicate +Codex-native workspace operations: + +- `read` +- `write` +- `edit` +- `apply_patch` +- `exec` +- `process` +- `update_plan` + +Remaining OpenClaw integration tools, such as messaging, sessions, media, cron, +browser, nodes, gateway, `heartbeat_respond`, and `web_search`, are available +through Codex tool search under the `openclaw` namespace. This keeps the initial +model context smaller. `sessions_yield` and message-tool-only source replies +stay direct because those are turn-control contracts. + +Set `codexDynamicToolsLoading: "direct"` only when connecting to a custom Codex +app-server that cannot search deferred dynamic tools or when debugging the full +tool payload. + +## 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: + +- A positive per-call `timeoutMs` argument. +- For `image_generate`, `agents.defaults.imageGenerationModel.timeoutMs`. +- For the media-understanding `image` tool, `tools.media.image.timeoutSeconds` + converted to milliseconds, or the 60 second media default. +- The 30 second dynamic-tool default. + +Dynamic tool budgets are capped at 600000 ms. On timeout, OpenClaw aborts the +tool signal where supported and returns a failed dynamic-tool response to Codex +so the turn can continue instead of leaving the session in `processing`. + +After OpenClaw responds to a Codex turn-scoped app-server request, the harness +also expects Codex to finish the native turn with `turn/completed`. If the +app-server goes quiet for `appServer.turnCompletionIdleTimeoutMs` after that +response, OpenClaw best-effort interrupts the Codex turn, records a diagnostic +timeout, and releases the OpenClaw session lane so follow-up chat messages are +not queued behind a stale native turn. + +Any non-terminal notification for the same turn, including +`rawResponseItem/completed`, disarms that short watchdog because Codex has +proven the turn is still alive. The longer terminal watchdog continues to +protect genuinely stuck turns. Timeout diagnostics include the last app-server +notification method and, for raw assistant response items, the item type, role, +id, and a bounded assistant text preview. + +## 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. + +If discovery fails or times out, OpenClaw uses a bundled fallback catalog for: + +- GPT-5.5 +- GPT-5.4 mini +- GPT-5.2 + +The current bundled harness is `@openai/codex` `0.130.0`. A `model/list` probe +against that bundled app-server returned: + +| Model id | Default | Hidden | Input modalities | Reasoning efforts | +| --------------------- | ------- | ------ | ---------------- | ------------------------ | +| `gpt-5.5` | Yes | No | text, image | low, medium, high, xhigh | +| `gpt-5.4` | No | No | text, image | low, medium, high, xhigh | +| `gpt-5.4-mini` | No | No | text, image | low, medium, high, xhigh | +| `gpt-5.3-codex` | No | No | text, image | low, medium, high, xhigh | +| `gpt-5.3-codex-spark` | No | No | text | low, medium, high, xhigh | +| `gpt-5.2` | No | No | text, image | low, medium, high, xhigh | + +Hidden models can be returned by the app-server catalog for internal or +specialized flows, but they are not normal model-picker choices. + +Tune discovery under `plugins.entries.codex.config.discovery`: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + discovery: { + enabled: true, + timeoutMs: 2500, + }, + }, + }, + }, + }, +} +``` + +Disable discovery when you want startup to avoid probing Codex and use only the +fallback catalog: + +```json5 +{ + 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. + +For OpenClaw workspace parity, the Codex harness resolves the other bootstrap +files, including `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, +`HEARTBEAT.md`, `BOOTSTRAP.md`, and `MEMORY.md` when present, and forwards them +through Codex developer instructions on `thread/start` and `thread/resume`. +This keeps workspace persona and profile context visible on the native Codex +behavior-shaping lane without duplicating `AGENTS.md`. + +## Environment overrides + +Environment overrides remain available for local testing: + +- `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` + +`OPENCLAW_CODEX_APP_SERVER_BIN` bypasses the managed binary when +`appServer.command` is unset. + +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` was removed. Use +`plugins.entries.codex.config.appServer.mode: "guardian"` instead, or +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` for one-off local testing. Config is +preferred for repeatable deployments because it keeps the plugin behavior in the +same reviewed file as the rest of the Codex harness setup. + +## Related + +- [Codex harness](/plugins/codex-harness) +- [Codex harness runtime](/plugins/codex-harness-runtime) +- [Native Codex plugins](/plugins/codex-native-plugins) +- [Codex Computer Use](/plugins/codex-computer-use) +- [OpenAI provider](/providers/openai) +- [Configuration reference](/gateway/configuration-reference) diff --git a/docs/plugins/codex-harness-runtime.md b/docs/plugins/codex-harness-runtime.md new file mode 100644 index 00000000000..b3f5dc697bd --- /dev/null +++ b/docs/plugins/codex-harness-runtime.md @@ -0,0 +1,212 @@ +--- +summary: "Runtime boundaries, hooks, tools, permissions, and diagnostics for the Codex harness" +title: "Codex harness runtime" +read_when: + - You need the Codex harness runtime support contract + - You are debugging native Codex tools, hooks, compaction, or feedback upload + - You are changing plugin behavior across PI and Codex harness turns +--- + +This page documents the runtime contract for Codex harness turns. For setup and +routing, start with [Codex harness](/plugins/codex-harness). For config fields, +see [Codex harness reference](/plugins/codex-harness-reference). + +## Overview + +Codex mode is not PI with a different model call underneath. Codex owns more of +the native model loop, and OpenClaw adapts its plugin, tool, session, and +diagnostic surfaces around that boundary. + +OpenClaw still owns channel routing, session files, visible message delivery, +OpenClaw dynamic tools, approvals, media delivery, and a transcript mirror. +Codex owns the canonical native thread, native model loop, native tool +continuation, and native compaction. + +## Thread bindings and model changes + +When an OpenClaw session is attached to an existing Codex thread, the next turn +sends the currently selected OpenAI model, approval policy, sandbox, and service +tier to app-server again. 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. + +## Visible replies and heartbeats + +When a source chat turn runs through the Codex harness, visible replies default +to the OpenClaw `message` tool if the deployment has not explicitly configured +`messages.visibleReplies`. The agent can still finish its Codex turn privately; +it only posts to the channel when it calls `message(action="send")`. Set +`messages.visibleReplies: "automatic"` to keep direct-chat final replies on the +legacy automatic delivery path. + +Codex heartbeat turns also get `heartbeat_respond` in the searchable OpenClaw +tool catalog by default, so the agent can record whether the wake should stay +quiet or notify without encoding that control flow in final text. + +Heartbeat-specific initiative guidance is sent as a Codex collaboration-mode +developer instruction on the heartbeat turn itself. Ordinary chat turns restore +Codex Default mode instead of carrying heartbeat philosophy in their normal +runtime prompt. + +## Hook boundaries + +The Codex harness has three hook layers: + +| Layer | Owner | Purpose | +| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | +| OpenClaw plugin hooks | OpenClaw | Product/plugin compatibility across PI 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. | + +OpenClaw does not use project or global Codex `hooks.json` files to route +OpenClaw plugin behavior. For the supported native tool and permission bridge, +OpenClaw injects per-thread Codex config for `PreToolUse`, `PostToolUse`, +`PermissionRequest`, and `Stop`. + +When Codex app-server approvals are enabled, meaning `approvalPolicy` is not +`"never"`, the default injected native hook config omits `PermissionRequest` so +Codex's app-server reviewer and OpenClaw's approval bridge handle real +escalations after review. Operators can explicitly add `permission_request` to +`nativeHookRelay.events` when they need the compatibility relay. + +Other Codex hooks such as `SessionStart` and `UserPromptSubmit` remain +Codex-level controls. They are not exposed as OpenClaw plugin hooks in the v1 +contract. + +For OpenClaw dynamic tools, OpenClaw executes the tool after Codex asks for the +call, so OpenClaw fires the plugin and middleware behavior it owns in the +harness adapter. For Codex-native tools, Codex owns the canonical tool record. +OpenClaw can mirror selected events, but it cannot rewrite the native Codex +thread unless Codex exposes that operation through app-server or native hook +callbacks. + +Compaction and LLM lifecycle projections come from Codex app-server +notifications and OpenClaw adapter state, not native Codex hook commands. +OpenClaw's `before_compaction`, `after_compaction`, `llm_input`, and +`llm_output` events are adapter-level observations, not byte-for-byte captures +of Codex's internal request or compaction payloads. + +Codex native `hook/started` and `hook/completed` app-server notifications are +projected as `codex_app_server.hook` agent events for trajectory and debugging. +They do not invoke OpenClaw plugin hooks. + +## V1 support contract + +Supported in Codex runtime v1: + +| 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 builds prompt overlays and projects context into the Codex turn before starting or resuming the thread. | +| Context engine lifecycle | Supported | Assemble, ingest, after-turn maintenance, and context-engine compaction coordination run for Codex turns. | +| 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.125.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. | + +Not supported in Codex runtime v1: + +| 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 observes compaction start and completion, but does not receive a stable kept/dropped list, token delta, or summary payload. | Needs richer Codex compaction events. | +| Compaction intervention | Current OpenClaw compaction hooks are notification-level in Codex mode. | 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. + +Codex app-server approval modes omit this native hook by default. This behavior +applies when `permission_request` is explicitly included in +`nativeHookRelay.events` or a compatibility runtime installs it. + +When an operator chooses `allow-always` for a Codex native permission request, +OpenClaw remembers that exact provider/session/tool input/cwd fingerprint for a +bounded session window. The remembered decision is intentionally exact-match +only: a changed command, arguments, tool payload, or cwd creates a fresh +approval. + +Codex MCP tool approval elicitations are routed through OpenClaw's plugin +approval flow when Codex marks `_meta.codex_approval_kind` as +`"mcp_tool_call"`. Codex `request_user_input` prompts are sent back to the +originating chat, and the next queued follow-up message answers that native +server request instead of being steered as extra context. Other MCP elicitation +requests fail closed. + +## Queue steering + +Active-run queue steering maps onto Codex app-server `turn/steer`. With the +default `messages.queue.mode: "steer"`, OpenClaw batches queued chat messages +for the configured quiet window and sends them as one `turn/steer` request in +arrival order. Legacy `queue` mode sends separate `turn/steer` requests. + +Codex review and manual compaction turns can reject same-turn steering. In that +case, OpenClaw uses the follow-up queue when the selected mode allows fallback. +See [Steering queue](/concepts/queue-steering). + +## Codex feedback upload + +When `/diagnostics [note]` is approved for a session using the native Codex +harness, OpenClaw also calls Codex app-server `feedback/upload` for relevant +Codex threads. The upload asks app-server to include logs for each listed thread +and spawned Codex subthreads when available. + +The upload goes through Codex's normal feedback path to OpenAI servers. If Codex +feedback is disabled in that app-server, the command returns the app-server +error. The completed diagnostics reply lists the channels, OpenClaw session ids, +Codex thread ids, and local `codex resume ` commands for the threads +that were sent. + +If you deny or ignore the approval, OpenClaw does not print those Codex ids and +does not send Codex feedback. The upload does not replace the local Gateway +diagnostics export. See [Diagnostics export](/gateway/diagnostics) for the +approval, privacy, local bundle, and group-chat behavior. + +Use `/codex diagnostics [note]` only when you specifically want the Codex +feedback upload for the currently attached thread without the full Gateway +diagnostics bundle. + +## Compaction and transcript mirror + +When the selected model uses the Codex harness, native thread compaction is +delegated to Codex app-server. OpenClaw keeps a transcript mirror for channel +history, search, `/new`, `/reset`, and future model or harness switching. + +The mirror includes the user prompt, final assistant text, and lightweight Codex +reasoning or plan records when the app-server emits them. Today, OpenClaw only +records native compaction start and completion signals. It does not yet expose a +human-readable compaction summary or an auditable list of which entries Codex +kept after compaction. + +Because Codex owns the canonical native thread, `tool_result_persist` does not +currently rewrite Codex-native tool result records. It only applies when +OpenClaw is writing an OpenClaw-owned session transcript tool result. + +## 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.imageGenerationModel`, `videoGenerationModel`, +`pdfModel`, and `messages.tts`. + +Text, images, video, music, TTS, approvals, and messaging-tool output continue +through the normal OpenClaw delivery path. Media generation does not require PI. + +## Related + +- [Codex harness](/plugins/codex-harness) +- [Codex harness reference](/plugins/codex-harness-reference) +- [Native Codex plugins](/plugins/codex-native-plugins) +- [Plugin hooks](/plugins/hooks) +- [Agent harness plugins](/plugins/sdk-agent-harness) +- [Diagnostics export](/gateway/diagnostics) +- [Trajectory export](/tools/trajectory) diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index 4d25b565573..6a6f24ad3ed 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -7,51 +7,53 @@ read_when: - You want Codex-only deployments to fail instead of falling back to PI --- -The bundled `codex` plugin lets OpenClaw run embedded agent turns through the -Codex app-server instead of the built-in PI harness. +The bundled `codex` plugin lets OpenClaw run embedded OpenAI agent turns +through Codex app-server instead of the built-in PI harness. -Use this when you want Codex to own the low-level agent session: model -discovery, native thread resume, native compaction, and app-server execution. -OpenClaw still owns chat channels, session files, model selection, tools, -approvals, media delivery, and the visible transcript mirror. +Use the Codex harness when you want Codex to own the low-level agent session: +native thread resume, native tool continuation, native compaction, and +app-server execution. OpenClaw still owns chat channels, session files, model +selection, OpenClaw dynamic tools, approvals, media delivery, and the visible +transcript mirror. -When a source chat turn runs through the Codex harness, visible replies default -to the OpenClaw `message` tool if the deployment has not explicitly configured -`messages.visibleReplies`. The agent can still finish its Codex turn privately; -it only posts to the channel when it calls `message(action="send")`. Set -`messages.visibleReplies: "automatic"` to keep direct-chat final replies on the -legacy automatic delivery path. +The normal setup uses canonical OpenAI model refs such as `openai/gpt-5.5`. +Do not configure `openai-codex/gpt-*` model refs. `openai-codex` is the auth +profile provider for Codex OAuth or Codex API-key profiles, not the model +provider prefix for new agent config. -Codex heartbeat turns also get `heartbeat_respond` in the searchable OpenClaw -tool catalog by default, so the agent can record whether the wake should stay -quiet or notify without encoding that control flow in final text. - -Heartbeat-specific initiative guidance is sent as a Codex collaboration-mode -developer instruction on the heartbeat turn itself. Ordinary chat turns restore -Codex Default mode instead of carrying heartbeat philosophy in their normal -runtime prompt. - -If you are trying to orient yourself, start with +For the broader model/provider/runtime split, start with [Agent runtimes](/concepts/agent-runtimes). The short version is: `openai/gpt-5.5` is the model ref, `codex` is the runtime, and Telegram, Discord, Slack, or another channel remains the communication surface. -## Quick config +## Requirements -Most users who want "Codex in OpenClaw" want this route: sign in with a -ChatGPT/Codex subscription, then run embedded agent turns through the native -Codex app-server runtime. The model ref still stays canonical as -`openai/gpt-*`; subscription auth comes from the Codex account/profile, not -from an `openai-codex/*` model prefix. +- OpenClaw with the bundled `codex` plugin available. +- If your config uses `plugins.allow`, include `codex`. +- Codex app-server `0.125.0` or newer. The bundled plugin manages a compatible + Codex app-server binary by default, so local `codex` commands on `PATH` do not + affect normal harness startup. +- Codex auth available through `openclaw models auth login --provider openai-codex`, + an app-server account in the agent's Codex home, or an explicit Codex API-key + auth profile. -First sign in with Codex OAuth if you have not already: +For auth precedence, environment isolation, custom app-server commands, model +discovery, and all config fields, see +[Codex harness reference](/plugins/codex-harness-reference). + +## Quickstart + +Most users who want Codex in OpenClaw want this path: sign in with a +ChatGPT/Codex subscription, enable the bundled `codex` plugin, and use a +canonical `openai/gpt-*` model ref. + +Sign in with Codex OAuth: ```bash openclaw models auth login --provider openai-codex ``` -Then enable the bundled `codex` plugin and use the canonical OpenAI model ref. -OpenAI agent turns select the Codex runtime by default: +Enable the bundled `codex` plugin and select an OpenAI agent model: ```json5 { @@ -70,7 +72,7 @@ OpenAI agent turns select the Codex runtime by default: } ``` -If your config uses `plugins.allow`, include `codex` there too: +If your config uses `plugins.allow`, add `codex` there too: ```json5 { @@ -85,197 +87,123 @@ If your config uses `plugins.allow`, include `codex` there too: } ``` -Do not use `openai-codex/gpt-*` in config. That prefix is a legacy route that -`openclaw doctor --fix` rewrites to `openai/gpt-*` across primary models, -fallbacks, heartbeat/subagent/compaction overrides, hooks, channel overrides, -and stale persisted session route pins. +Restart the gateway after changing plugin config. If an existing chat already +has a session, use `/new` or `/reset` before testing runtime changes so the next +turn resolves the harness from current config. -## What this plugin changes +## Configuration -The bundled `codex` plugin contributes several separate capabilities: +The quickstart config is the minimum viable Codex harness config. Set Codex +harness options in OpenClaw config, and use the CLI only for Codex auth: -| Capability | How you use it | What it does | -| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | -| Native embedded runtime | `openai/gpt-*` agent model refs | Runs OpenClaw embedded agent turns through Codex app-server. | -| Native chat-control commands | `/codex bind`, `/codex resume`, `/codex steer`, ... | Binds and controls Codex app-server threads from a messaging conversation. | -| Codex app-server provider/catalog | `codex` internals, surfaced through the harness | Lets the runtime discover and validate app-server models. | -| Codex media-understanding path | `codex/*` image-model compatibility paths | Runs bounded Codex app-server turns for supported image understanding models. | -| Native hook relay | Plugin hooks around Codex-native events | Lets OpenClaw observe/block supported Codex-native tool/finalization events. | +| Need | Set | Where | +| -------------------------------------- | ------------------------------------------------------------------ | ------------------------------ | +| Enable the harness | `plugins.entries.codex.enabled: true` | OpenClaw config | +| Keep an allowlisted plugin install | Include `codex` in `plugins.allow` | OpenClaw config | +| Route OpenAI agent turns through Codex | `agents.defaults.model` or `agents.list[].model` as `openai/gpt-*` | OpenClaw agent config | +| Sign in with Codex OAuth | `openclaw models auth login --provider openai-codex` | CLI auth profile | +| Fail closed when Codex is unavailable | Provider or model `agentRuntime.id: "codex"` | OpenClaw model/provider config | +| Use direct OpenAI API traffic | Provider or model `agentRuntime.id: "pi"` with normal OpenAI auth | OpenClaw model/provider config | +| Tune app-server behavior | `plugins.entries.codex.config.appServer.*` | Codex plugin config | +| Enable native Codex plugin apps | `plugins.entries.codex.config.codexPlugins.*` | Codex plugin config | +| Enable Codex Computer Use | `plugins.entries.codex.config.computerUse.*` | Codex plugin config | -Enabling the plugin makes those capabilities available. It does **not**: +Use `openai/gpt-*` model refs for Codex-backed OpenAI agent turns. +`openai-codex` is only the auth-profile provider name for Codex OAuth and +Codex API-key profiles. Do not write new `openai-codex/gpt-*` model refs. -- replace direct OpenAI API-key surfaces such as images, embeddings, speech, or - realtime -- convert `openai-codex/*` model refs without `openclaw doctor --fix` -- make ACP/acpx the default Codex path -- use stale whole-agent or session runtime pins for routing -- replace OpenClaw channel delivery, session files, auth-profile storage, or - message routing +The rest of this page covers common variants users must choose between: +deployment shape, fail-closed routing, guardian approval policy, native Codex +plugins, and Computer Use. For full option lists, defaults, enums, discovery, +environment isolation, timeouts, and app-server transport fields, see +[Codex harness reference](/plugins/codex-harness-reference). -The same plugin also owns the native `/codex` chat-control command surface. If -the plugin is enabled and the user asks to bind, resume, steer, stop, or inspect -Codex threads from chat, agents should prefer `/codex ...` over ACP. ACP remains -the explicit fallback when the user asks for ACP/acpx or is testing the ACP -Codex adapter. +## Verify Codex runtime -Native Codex turns keep OpenClaw plugin hooks as the public compatibility layer. -These are in-process OpenClaw hooks, not Codex `hooks.json` command hooks: +Use `/status` in the chat where you expect Codex. A Codex-backed OpenAI agent +turn shows: -- `before_prompt_build` -- `before_compaction`, `after_compaction` -- `llm_input`, `llm_output` -- `before_tool_call`, `after_tool_call` -- `before_message_write` for mirrored transcript records -- `before_agent_finalize` through Codex `Stop` relay -- `agent_end` +```text +Runtime: OpenAI Codex +``` -Plugins can also register runtime-neutral tool-result middleware to rewrite -OpenClaw dynamic tool results after OpenClaw executes the tool and before the -result is returned to Codex. This is separate from the public -`tool_result_persist` plugin hook, which transforms OpenClaw-owned transcript -tool-result writes. +Then check Codex app-server state: -For the plugin hook semantics themselves, see [Plugin hooks](/plugins/hooks) -and [Plugin guard behavior](/tools/plugin). +```text +/codex status +/codex models +``` -OpenAI agent model refs use the harness by default. New configs should keep -OpenAI model refs canonical as `openai/gpt-*`; provider/model -`agentRuntime.id: "codex"` is still valid but no longer required for OpenAI -agent turns. Legacy `codex/*` model refs still auto-select the harness for -compatibility, but -runtime-backed legacy provider prefixes are not shown as normal model/provider -choices. +`/codex status` reports app-server connectivity, account, rate limits, MCP +servers, and skills. `/codex models` lists the live Codex app-server catalog for +the harness and account. If `/status` is surprising, see +[Troubleshooting](#troubleshooting). -If any configured model route is still `openai-codex/*`, `openclaw doctor --fix` -rewrites it to `openai/*` and preserves existing `openai-codex` auth profile -overrides. It does not pin the whole agent to `agentRuntime.id: "codex"` because -canonical OpenAI refs already select the Codex harness automatically. +## Routing and model selection -## Route map +Keep provider refs and runtime policy separate: -Use this table before changing config: +- Use `openai/gpt-*` for OpenAI agent turns through Codex. +- Do not use `openai-codex/gpt-*` in config. Run `openclaw doctor --fix` to + repair legacy refs and stale session route pins. +- `agentRuntime.id: "codex"` is optional for normal OpenAI auto mode, but useful + when a deployment should fail closed if Codex is unavailable. +- `agentRuntime.id: "pi"` opts a provider or model into direct PI behavior when + that is intentional. +- `/codex ...` controls native Codex app-server conversations from chat. +- ACP/acpx is a separate external harness path. Use it only when the user asks + for ACP/acpx or an external harness adapter. -| Desired behavior | Model ref | Runtime config | Auth/profile route | Expected status label | -| ---------------------------------------------------- | -------------------------- | -------------------------------------------------------- | ------------------------------ | ---------------------------- | -| ChatGPT/Codex subscription with native Codex runtime | `openai/gpt-*` | omitted or provider/model `agentRuntime.id: "codex"` | Codex OAuth or Codex account | `Runtime: OpenAI Codex` | -| OpenAI API-key auth for agent models | `openai/gpt-*` | omitted or provider/model `agentRuntime.id: "codex"` | `openai-codex` API-key profile | `Runtime: OpenAI Codex` | -| Legacy config that needs doctor repair | `openai-codex/gpt-*` | preserved or automatic | Existing configured auth | Recheck after `doctor --fix` | -| Mixed providers with conservative auto mode | provider-specific refs | omitted unless a provider/model needs a runtime override | Per selected provider | Depends on selected runtime | -| Explicit Codex ACP adapter session | ACP prompt/model dependent | `sessions_spawn` with `runtime: "acp"` | ACP backend auth | ACP task/session status | +Common command routing: -The important split is provider versus runtime: +| User intent | Use | +| ------------------------------- | --------------------------------------- | +| Attach the current chat | `/codex bind [--cwd ]` | +| Resume an existing Codex thread | `/codex resume ` | +| List or filter Codex threads | `/codex threads [filter]` | +| Send Codex feedback only | `/codex diagnostics [note]` | +| Start an ACP/acpx task | ACP/acpx session commands, not `/codex` | -- `openai-codex/*` is a legacy route that doctor rewrites. -- Provider/model `agentRuntime.id: "codex"` requires the Codex harness and fails - closed if it is unavailable. -- Provider/model `agentRuntime.id: "auto"` lets registered harnesses claim - matching provider routes; OpenAI agent refs resolve to Codex instead of PI. -- `/codex ...` answers "which native Codex conversation should this chat bind - or control?" -- ACP answers "which external harness process should acpx launch?" +| Use case | Configure | Verify | Notes | +| ---------------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------- | ---------------------------------- | +| ChatGPT/Codex subscription with native Codex runtime | `openai/gpt-*` plus enabled `codex` plugin | `/status` shows `Runtime: OpenAI Codex` | Recommended path | +| Fail closed if Codex is unavailable | Provider or model `agentRuntime.id: "codex"` | Turn fails instead of PI fallback | Use for Codex-only deployments | +| Direct OpenAI API-key traffic through PI | Provider or model `agentRuntime.id: "pi"` and normal OpenAI auth | `/status` shows PI runtime | Use only when PI is intentional | +| Legacy config | `openai-codex/gpt-*` | `openclaw doctor --fix` rewrites it | Do not write new config this way | +| ACP/acpx Codex adapter | ACP `sessions_spawn({ runtime: "acp" })` | ACP task/session status | Separate from native Codex harness | -## Pick the right model prefix +`agents.defaults.imageModel` follows the same prefix split. Use `openai/gpt-*` +for the normal OpenAI route and `codex/gpt-*` only when image understanding +should run through a bounded Codex app-server turn. Do not use +`openai-codex/gpt-*`; doctor rewrites that legacy prefix to `openai/gpt-*`. -OpenAI-family routes are prefix-specific. For the common subscription plus -native Codex runtime setup, use `openai/*`. -Treat `openai-codex/*` as legacy config that doctor should rewrite: +## Deployment patterns -| Model ref | Runtime path | Use when | -| ------------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------- | -| `openai/gpt-5.4` | Codex app-server harness for agent turns | You want OpenAI agent models through Codex. | -| `openai-codex/gpt-5.5` | Legacy route repaired by doctor | You are on old config; run `openclaw doctor --fix` to rewrite it. | -| `openai/gpt-5.5` + `openai-codex` API-key profile | Codex app-server harness | You want API-key auth for an OpenAI agent model. | +### Basic Codex deployment -GPT-5.5 can appear on both direct OpenAI API-key and Codex subscription routes -when your account exposes them. Use `openai/gpt-5.5` with the Codex app-server -harness for native Codex runtime. For direct API-key traffic through PI, opt in -with provider/model `agentRuntime.id: "pi"` and a normal `openai` auth profile. +Use the quickstart config when all OpenAI agent turns should use Codex by +default. -Legacy `codex/gpt-*` refs remain accepted as compatibility aliases. Doctor -compatibility migration rewrites legacy runtime refs to canonical model refs -and records the runtime policy separately. New native app-server harness configs -should use `openai/gpt-*`; explicit provider/model `agentRuntime.id: "codex"` -is only needed when you want the policy written down. +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + }, + }, + }, + agents: { + defaults: { + model: "openai/gpt-5.5", + }, + }, +} +``` -`agents.defaults.imageModel` follows the same prefix split. Use -`openai/gpt-*` for the normal OpenAI route and `codex/gpt-*` when image -understanding should run through a bounded Codex app-server turn. Do not use -`openai-codex/gpt-*`; doctor rewrites that legacy prefix to `openai/gpt-*`. The -Codex app-server model must advertise image input support; text-only Codex -models fail before the media turn starts. +### Mixed provider deployment -Use `/status` to confirm the effective harness for the current session. If the -selection is surprising, enable debug logging for the `agents/harness` subsystem -and inspect the gateway's structured `agent harness selected` record. It -includes the selected harness id, selection reason, runtime/fallback policy, and, -in `auto` mode, each plugin candidate's support result. - -### What doctor warnings mean - -`openclaw doctor` warns when configured model refs or persisted session route -state still use `openai-codex/*`. `openclaw doctor --fix` rewrites those routes -to `openai/`. Canonical OpenAI agent refs already select the native Codex -harness, so doctor does not pin the whole agent to Codex. - -Whole-session and whole-agent runtime pins are legacy state. Runtime selection -now comes from provider/model policy; `openclaw doctor --fix` removes stale -session pins and old whole-agent runtime config so they do not mask the selected -provider/model route. - -`/status` shows the effective model runtime. The default PI harness appears as -`Runtime: OpenClaw Pi Default`, and the Codex app-server harness appears as -`Runtime: OpenAI Codex`. - -## Requirements - -- OpenClaw with the bundled `codex` plugin available. -- Codex app-server `0.125.0` or newer. The bundled plugin manages a compatible - Codex app-server binary by default, so local `codex` commands on `PATH` do - not affect normal harness startup. -- Codex auth available to the app-server process or to OpenClaw's Codex auth - bridge. Local app-server launches use an OpenClaw-managed Codex home for each - agent and an isolated child `HOME`, so they do not read your personal - `~/.codex` account, skills, plugins, config, thread state, or native - `$HOME/.agents/skills` by default. - -The plugin blocks older or unversioned app-server handshakes. That keeps -OpenClaw on the protocol surface it has been tested against. - -For live and Docker smoke tests, auth usually comes from the Codex CLI account -or an OpenClaw `openai-codex` auth profile. Local stdio app-server launches can -also fall back to `CODEX_API_KEY` / `OPENAI_API_KEY` when no account is present. - -## 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. - -For OpenClaw workspace parity, the Codex harness resolves the other bootstrap -files (`SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, -`BOOTSTRAP.md`, and `MEMORY.md` when present) and forwards them through Codex -developer instructions on `thread/start` and `thread/resume`. This keeps -`SOUL.md` and related workspace persona/profile context visible on the native -Codex behavior-shaping lane without duplicating `AGENTS.md`. - -## Add Codex alongside other models - -Do not set a whole-agent runtime. Whole-agent runtime pins are legacy and -ignored, and they were the source of mixed-provider traps after upgrades. Keep -runtime policy on the provider or model that needs it. - -Use one of these shapes instead: - -- Use `openai/gpt-*` for OpenAI agent turns; Codex is selected by default. -- Put runtime overrides on `models.providers..agentRuntime` or on a - model entry such as `agents.defaults.models["anthropic/claude-opus-4-7"].agentRuntime`. -- Use legacy `codex/*` refs only for compatibility. New configs should prefer - `openai/*`; add an explicit Codex runtime policy only when you need to make - the provider/model rule strict. - -For example, this keeps mixed-provider routing ergonomic while using OpenAI -through Codex by default and Claude through PI: +This shape keeps Claude as the default agent and adds a named Codex agent: ```json5 { @@ -306,39 +234,14 @@ through Codex by default and Claude through PI: } ``` -With this shape: +With this config, the `main` agent uses its normal provider path and the +`codex` agent uses Codex app-server. -- The default `main` agent uses the normal provider path and PI compatibility fallback. -- The `codex` agent uses the Codex app-server harness. -- If Codex is missing or unsupported for the `codex` agent, the turn fails - instead of quietly using PI. +### Fail-closed Codex deployment -## Agent command routing - -Agents should route user requests by intent, not by the word "Codex" alone: - -| User asks for... | Agent should use... | -| ------------------------------------------------------ | ------------------------------------------------ | -| "Bind this chat to Codex" | `/codex bind` | -| "Resume Codex thread `` here" | `/codex resume ` | -| "Show Codex threads" | `/codex threads` | -| "File a support report for a bad Codex run" | `/diagnostics [note]` | -| "Only send Codex feedback for this attached thread" | `/codex diagnostics [note]` | -| "Use my ChatGPT/Codex subscription with Codex runtime" | `openai/*` | -| "Repair old `openai-codex/*` config/session pins" | `openclaw doctor --fix` | -| "Run Codex through ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | -| "Start Claude Code/Gemini/OpenCode/Cursor in a thread" | ACP/acpx, not `/codex` and not native sub-agents | - -OpenClaw only advertises ACP spawn guidance to agents when ACP is enabled, -dispatchable, and backed by a loaded runtime backend. If ACP is not available, -the system prompt and plugin skills should not teach the agent about ACP -routing. - -## Codex-only deployments - -For OpenAI agent turns, `openai/gpt-*` already resolves to Codex. If you need a -strict written policy, put it on the OpenAI provider or model. Explicit plugin -runtimes fail closed and are never silently retried through PI: +For OpenAI agent turns, `openai/gpt-*` already resolves to Codex when the +bundled plugin is available. Add explicit runtime policy when you want a written +fail-closed rule: ```json5 { @@ -351,80 +254,30 @@ runtimes fail closed and are never silently retried through PI: }, }, }, - agents: { defaults: { model: "openai/gpt-5.5" } }, + agents: { + defaults: { + model: "openai/gpt-5.5", + }, + }, + plugins: { + entries: { + codex: { + enabled: true, + }, + }, + }, } ``` With Codex forced, OpenClaw fails early if the Codex plugin is disabled, the app-server is too old, or the app-server cannot start. -## Per-agent Codex +## App-server policy -You can make one agent Codex-strict while the default agent keeps normal -selection by using a per-agent model runtime override: - -```json5 -{ - agents: { - list: [ - { - id: "main", - default: true, - model: "anthropic/claude-opus-4-6", - }, - { - id: "codex", - name: "Codex", - model: "openai/gpt-5.5", - models: { - "openai/gpt-5.5": { - agentRuntime: { - id: "codex", - }, - }, - }, - }, - ], - }, -} -``` - -Use normal session commands to switch agents and models. `/new` creates a fresh -OpenClaw session and the Codex harness creates or resumes its sidecar app-server -thread as needed. `/reset` clears the OpenClaw session binding for that thread -and lets the next turn resolve the harness from current config again. - -## Model discovery - -By default, the Codex plugin asks the app-server for available models. Model -availability is owned by the Codex app-server harness, 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. - -If discovery fails or times out, OpenClaw uses a bundled fallback catalog for: - -- GPT-5.5 -- GPT-5.4 mini -- GPT-5.2 - -The current bundled harness is `@openai/codex` `0.130.0`. A `model/list` probe -against that bundled app-server returned: - -| Model id | Default | Hidden | Input modalities | Reasoning efforts | -| --------------------- | ------- | ------ | ---------------- | ------------------------ | -| `gpt-5.5` | Yes | No | text, image | low, medium, high, xhigh | -| `gpt-5.4` | No | No | text, image | low, medium, high, xhigh | -| `gpt-5.4-mini` | No | No | text, image | low, medium, high, xhigh | -| `gpt-5.3-codex` | No | No | text, image | low, medium, high, xhigh | -| `gpt-5.3-codex-spark` | No | No | text | low, medium, high, xhigh | -| `gpt-5.2` | No | No | text, image | low, medium, high, xhigh | - -Hidden models can be returned by the app-server catalog for internal or -specialized flows, but they are not normal model-picker choices. - -You can tune discovery under `plugins.entries.codex.config.discovery`: +By default, the plugin starts OpenClaw's managed Codex binary locally with stdio +transport. Set `appServer.command` only when you intentionally want to run a +different executable. Use WebSocket transport only when an app-server is already +running elsewhere: ```json5 { @@ -433,9 +286,10 @@ You can tune discovery under `plugins.entries.codex.config.discovery`: codex: { enabled: true, config: { - discovery: { - enabled: true, - timeoutMs: 2500, + appServer: { + transport: "websocket", + url: "ws://gateway-host:39175", + authToken: "${CODEX_APP_SERVER_TOKEN}", }, }, }, @@ -444,53 +298,13 @@ You can tune discovery under `plugins.entries.codex.config.discovery`: } ``` -Disable discovery when you want startup to avoid probing Codex and stick to the -fallback catalog: - -```json5 -{ - plugins: { - entries: { - codex: { - enabled: true, - config: { - discovery: { - enabled: false, - }, - }, - }, - }, - }, -} -``` - -## App-server connection and policy - -By default, the plugin starts OpenClaw's managed Codex binary locally with: - -```bash -codex app-server --listen stdio:// -``` - -The managed binary is shipped with the `codex` plugin package. This keeps the -app-server version tied to the bundled plugin instead of whichever separate -Codex CLI happens to be installed locally. Set `appServer.command` only when -you intentionally want to run a different executable. - -By default, OpenClaw starts local Codex harness sessions in YOLO mode: +Local stdio app-server sessions default to the trusted local operator posture: `approvalPolicy: "never"`, `approvalsReviewer: "user"`, and -`sandbox: "danger-full-access"`. This is the trusted local operator posture used -for autonomous heartbeats: Codex can use shell and network tools without -stopping on native approval prompts that nobody is around to answer. On local -stdio Codex app-server installs where Codex's system requirements file -disallows the implicit YOLO approval, reviewer, or sandbox value, OpenClaw -treats the implicit default as guardian instead and selects allowed guardian -permissions so it does not send an override that Codex app-server will reject. -Hostname-matching `[[remote_sandbox_config]]` entries in the same requirements -file are honored for the sandbox default decision. +`sandbox: "danger-full-access"`. If local Codex requirements disallow that +implicit YOLO posture, OpenClaw selects allowed guardian permissions instead. -To opt in to Codex guardian-reviewed approvals, set `appServer.mode: -"guardian"`: +Use guardian mode when you want Codex native auto-review before sandbox escapes +or extra permissions: ```json5 { @@ -510,217 +324,71 @@ To opt in to Codex guardian-reviewed approvals, set `appServer.mode: } ``` -Guardian mode uses Codex's native auto-review approval path. When Codex asks to -leave the sandbox, write outside the workspace, or add permissions like network -access, Codex routes that approval request to the native reviewer instead of a -human prompt. The reviewer applies Codex's risk framework and approves or denies -the specific request. Use Guardian when you want more guardrails than YOLO mode -but still need unattended agents to make progress. +Guardian mode expands to Codex app-server approvals, usually +`approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"`, and +`sandbox: "workspace-write"` when the local requirements allow those values. -The `guardian` preset expands to `approvalPolicy: "on-request"`, -`approvalsReviewer: "auto_review"`, and `sandbox: "workspace-write"`. -Individual policy fields still override `mode`, so advanced deployments can mix -the preset with explicit choices. The older `guardian_subagent` reviewer value is -still accepted as a compatibility alias, but new configs should use -`auto_review`. +For every app-server field, auth order, environment isolation, discovery, and +timeout behavior, see [Codex harness reference](/plugins/codex-harness-reference). -For an already-running app-server, use WebSocket transport: +## Commands and diagnostics -```json5 -{ - plugins: { - entries: { - codex: { - enabled: true, - config: { - appServer: { - transport: "websocket", - url: "ws://127.0.0.1:39175", - authToken: "${CODEX_APP_SERVER_TOKEN}", - requestTimeoutMs: 60000, - }, - }, - }, - }, - }, -} -``` +The bundled plugin registers `/codex` as a slash command on any channel that +supports OpenClaw text commands. -Stdio app-server launches inherit OpenClaw's process environment by default, -but OpenClaw owns the Codex app-server account bridge and sets both -`CODEX_HOME` and `HOME` to per-agent directories under that agent's OpenClaw -state. Codex's own skill loader reads `$CODEX_HOME/skills` and -`$HOME/.agents/skills`, so both values are isolated for local app-server -launches. That keeps Codex-native skills, plugins, config, accounts, and thread -state scoped to the OpenClaw agent instead of leaking in from the operator's -personal Codex CLI home. +Common forms: -OpenClaw plugins and OpenClaw skill snapshots still flow through OpenClaw's own -plugin registry and skill loader. Personal Codex CLI assets do not. If you have -useful Codex CLI skills or plugins that should become part of an OpenClaw agent, -inventory them explicitly: +- `/codex status` checks app-server connectivity, models, account, rate limits, + MCP servers, and skills. +- `/codex models` lists live Codex app-server models. +- `/codex threads [filter]` lists recent Codex app-server threads. +- `/codex resume ` attaches the current OpenClaw session to an + existing Codex thread. +- `/codex compact` asks Codex app-server to compact the attached thread. +- `/codex review` starts Codex native review for the attached thread. +- `/codex diagnostics [note]` asks before sending Codex feedback for the + attached thread. +- `/codex account` shows account and rate-limit status. +- `/codex mcp` lists Codex app-server MCP server status. +- `/codex skills` lists Codex app-server skills. + +For most support reports, start with `/diagnostics [note]` in the conversation +where the bug happened. It creates one Gateway diagnostics report and, for Codex +harness sessions, asks for approval to send the relevant Codex feedback bundle. +See [Diagnostics export](/gateway/diagnostics) for the privacy model and group +chat behavior. + +Use `/codex diagnostics [note]` only when you specifically want the Codex +feedback upload for the currently attached thread without the full Gateway +diagnostics bundle. + +### Inspect Codex threads locally + +The fastest way to inspect a bad Codex run is often to open the native Codex +thread directly: ```bash -openclaw migrate codex --dry-run -openclaw migrate apply codex --yes +codex resume ``` -The Codex migration provider copies skills into the current OpenClaw agent -workspace. For source-installed `openai-curated` Codex plugins, migration also -calls Codex app-server `plugin/install` and records explicit native plugin -config under `plugins.entries.codex.config.codexPlugins`. Codex config files, -hooks, and cached plugin bundles that are not source-installed curated plugins -remain report-only manual-review items. +Get the thread id from the completed `/diagnostics` reply, `/codex binding`, or +`/codex threads [filter]`. -Auth is selected in this order: - -1. An explicit OpenClaw Codex auth profile for the agent. -2. The app-server's existing account in that agent's Codex home. -3. For local stdio app-server launches only, `CODEX_API_KEY`, then - `OPENAI_API_KEY`, when no app-server account is present and OpenAI auth is - still required. - -When OpenClaw sees a ChatGPT subscription-style Codex auth profile, it removes -`CODEX_API_KEY` and `OPENAI_API_KEY` from the spawned Codex child process. That -keeps Gateway-level API keys available for embeddings or direct OpenAI models -without making native Codex app-server turns bill through the API by accident. -Explicit Codex API-key profiles and local stdio env-key fallback use app-server -login instead of inherited child-process env. WebSocket app-server connections -do not receive Gateway env API-key fallback; use an explicit auth profile or the -remote app-server's own account. - -If a deployment needs additional environment isolation, add those variables to -`appServer.clearEnv`: - -```json5 -{ - plugins: { - entries: { - codex: { - enabled: true, - config: { - appServer: { - clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"], - }, - }, - }, - }, - }, -} -``` - -`appServer.clearEnv` only affects the spawned Codex app-server child process. - -Codex dynamic tools default to the `native-first` profile and `searchable` -loading. In that mode, OpenClaw does not expose dynamic tools that duplicate -Codex-native workspace operations: `read`, `write`, `edit`, `apply_patch`, -`exec`, `process`, and `update_plan`. Remaining OpenClaw integration tools such -as messaging, sessions, media, cron, browser, nodes, gateway, -`heartbeat_respond`, and `web_search` are available through Codex tool search -under the `openclaw` namespace, keeping the initial model context smaller. -`sessions_yield` and message-tool-only source replies stay direct because those -are turn-control contracts. Heartbeat collaboration instructions tell Codex to -search for `heartbeat_respond` before ending a heartbeat turn when the tool is -not already loaded. - -Set `codexDynamicToolsLoading: "direct"` only when connecting to a custom Codex -app-server that cannot search deferred dynamic tools or when debugging the full -tool payload. - -Supported top-level Codex plugin fields: - -| Field | Default | Meaning | -| -------------------------- | ---------------- | ----------------------------------------------------------------------------------------- | -| `codexDynamicToolsProfile` | `"native-first"` | Use `"openclaw-compat"` to expose the full OpenClaw dynamic tool set to Codex app-server. | -| `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 for migrated source-installed curated plugins. | - -Supported `appServer` fields: - -| Field | Default | Meaning | -| ----------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `transport` | `"stdio"` | `"stdio"` spawns Codex; `"websocket"` connects to `url`. | -| `command` | managed Codex binary | Executable for stdio transport. Leave unset to use the managed binary; set it only for an explicit override. | -| `args` | `["app-server", "--listen", "stdio://"]` | Arguments for stdio transport. | -| `url` | unset | WebSocket app-server URL. | -| `authToken` | unset | Bearer token for WebSocket transport. | -| `headers` | `{}` | Extra WebSocket headers. | -| `clearEnv` | `[]` | Extra environment variable names removed from the spawned stdio app-server process after OpenClaw builds its inherited environment. `CODEX_HOME` and `HOME` are reserved for OpenClaw's per-agent Codex isolation on local launches. | -| `requestTimeoutMs` | `60000` | Timeout for app-server control-plane calls. | -| `turnCompletionIdleTimeoutMs` | `60000` | Quiet window after a turn-scoped Codex app-server request while OpenClaw waits for `turn/completed`. Raise this for slow post-tool or status-only synthesis phases. | -| `mode` | `"yolo"` unless local Codex requirements disallow YOLO | Preset for YOLO or guardian-reviewed execution. Local stdio requirements that omit `danger-full-access`, `never` approval, or the `user` reviewer make the implicit default guardian. | -| `approvalPolicy` | `"never"` or an allowed guardian approval policy | Native Codex approval policy sent to thread start/resume/turn. Guardian defaults prefer `"on-request"` when allowed. | -| `sandbox` | `"danger-full-access"` or an allowed guardian sandbox | Native Codex sandbox mode sent to thread start/resume. Guardian defaults prefer `"workspace-write"` when allowed, otherwise `"read-only"`. | -| `approvalsReviewer` | `"user"` or an allowed guardian reviewer | Use `"auto_review"` to let Codex review native approval prompts when allowed, otherwise `guardian_subagent` or `user`. `guardian_subagent` remains a legacy alias. | -| `serviceTier` | unset | Optional Codex app-server service tier. `"priority"` enables fast-mode routing, `"flex"` requests flex processing, `null` clears the override, and legacy `"fast"` is accepted as `"priority"`. | - -OpenClaw-owned dynamic tool calls are bounded independently from -`appServer.requestTimeoutMs`: Codex `item/tool/call` requests use a 30 second -OpenClaw watchdog by default. A positive per-call `timeoutMs` argument extends -or shortens that specific tool budget. The `image_generate` tool also uses -`agents.defaults.imageGenerationModel.timeoutMs` when the tool call does not -provide its own timeout, and the media-understanding `image` tool uses -`tools.media.image.timeoutSeconds` or its 60 second media default. Dynamic tool -budgets are capped at 600000 ms. On timeout, OpenClaw aborts the tool signal -where supported and returns a failed dynamic-tool response to Codex so the turn -can continue instead of leaving the session in `processing`. - -After OpenClaw responds to a Codex turn-scoped app-server request, the harness -also expects Codex to finish the native turn with `turn/completed`. If the -app-server goes quiet for `appServer.turnCompletionIdleTimeoutMs` after that -response, OpenClaw best-effort interrupts the Codex turn, records a diagnostic -timeout, and releases the OpenClaw session lane so follow-up chat messages are -not queued behind a stale native turn. Any non-terminal notification for the -same turn, including `rawResponseItem/completed`, disarms that short watchdog -because Codex has proven the turn is still alive; the longer terminal watchdog -continues to protect genuinely stuck turns. Timeout diagnostics include the -last app-server notification method and, for raw assistant response items, the -item type, role, id, and a bounded assistant text preview. - -Environment overrides remain available for local testing: - -- `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` - -`OPENCLAW_CODEX_APP_SERVER_BIN` bypasses the managed binary when -`appServer.command` is unset. - -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` was removed. Use -`plugins.entries.codex.config.appServer.mode: "guardian"` instead, or -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` for one-off local testing. Config is -preferred for repeatable deployments because it keeps the plugin behavior in the -same reviewed file as the rest of the Codex harness setup. +For upload mechanics and runtime-level diagnostics boundaries, see +[Codex harness runtime](/plugins/codex-harness-runtime#codex-feedback-upload). ## Native Codex plugins Native Codex plugin support uses Codex app-server's own app and plugin capabilities in the same Codex thread as the OpenClaw harness turn. OpenClaw does not translate Codex plugins into synthetic `codex_plugin_*` OpenClaw -dynamic tools. That keeps plugin calls in the native Codex transcript and avoids -starting a second ephemeral Codex thread for each plugin invocation. +dynamic tools. -Codex plugins only work when the selected OpenClaw agent runtime is the native -Codex harness. The `codexPlugins` config has no effect on Pi runs, normal -OpenAI provider runs, ACP conversation bindings, or other harnesses, because -those paths do not create Codex app-server threads with native `apps` config. +`codexPlugins` affects only sessions that select the native Codex harness. It +has no effect on PI runs, normal OpenAI provider runs, ACP conversation +bindings, or other harnesses. -V1 support is intentionally narrow: - -- Only `openai-curated` plugins that were already installed in the source Codex - app-server inventory are migration-eligible. -- Migration writes explicit plugin identities with `marketplaceName` and - `pluginName`; it does not write local `marketplacePath` cache paths. -- `codexPlugins.enabled` is the global enablement switch. There is no - `plugins["*"]` wildcard and no config key that grants arbitrary install - authority. -- Unsupported marketplaces, cached plugin bundles, hooks, and Codex config files - are preserved in the migration report for manual review. - -Example migrated config: +Minimal migrated config: ```json5 { @@ -752,485 +420,95 @@ or replaces a stale Codex thread binding. It is not recomputed on every turn. After changing `codexPlugins`, use `/new`, `/reset`, or restart the gateway so future Codex harness sessions start with the updated app set. -OpenClaw reads Codex app inventory through app-server `app/list`, caches it for -one hour, and refreshes stale or missing entries asynchronously. A plugin app is -exposed only when OpenClaw can map it back to the migrated plugin through stable -ownership: an exact app id from plugin detail, a known MCP server name, or -unique stable metadata. Display-name-only or ambiguous ownership is excluded -until the next inventory refresh proves ownership. +For migration eligibility, app inventory, destructive action policy, +elicitations, and native plugin diagnostics, see +[Native Codex plugins](/plugins/codex-native-plugins). -Plugin-owned app tools use Codex's native app configuration. OpenClaw injects a -restrictive `config.apps` patch for the Codex thread: `_default` is disabled and -only apps owned by enabled migrated plugins are enabled. OpenClaw sets -app-level `destructive_enabled` from the effective global/per-plugin -`allow_destructive_actions` policy and lets Codex enforce destructive tool -metadata from its native app tool annotations. Plugin apps are emitted with -`open_world_enabled: true`; OpenClaw does not expose a separate plugin -open-world policy knob. OpenClaw does not maintain per-plugin destructive -tool-name deny lists. Tool approval mode is prompted by default for plugin -apps, because OpenClaw does not have an interactive app-elicitation UI in this -same-thread path. - -Destructive plugin elicitations fail closed by default: - -- Global `allow_destructive_actions` defaults to `false`. -- Per-plugin `allow_destructive_actions` overrides the global policy for that - plugin. -- When policy is `false`, OpenClaw returns a deterministic decline. -- When policy is `true`, OpenClaw auto-accepts only safe schemas it can map to - an approval response, such as a boolean approve field. -- Missing plugin identity, ambiguous ownership, a missing turn id, a wrong turn - id, or an unsafe elicitation schema declines instead of prompting. - -Common diagnostics: - -- `auth_required`: migration installed the plugin but one of its apps still - needs authentication. The explicit plugin entry is written disabled until you - reauthorize and enable it. -- `marketplace_missing` or `plugin_missing`: the target Codex app-server cannot - see the expected `openai-curated` marketplace or plugin. -- `app_inventory_missing` or `app_inventory_stale`: app readiness came from an - empty or stale cache; OpenClaw schedules an async refresh and excludes plugin - apps until ownership/readiness is known. -- `app_ownership_ambiguous`: app inventory only matched by display name, so the - app is not exposed to the Codex thread. - -## Computer use +## Computer Use Computer Use is covered in its own setup guide: [Codex Computer Use](/plugins/codex-computer-use). The short version: OpenClaw does not vendor the desktop-control app or execute desktop actions itself. It prepares Codex app-server, verifies that the -`computer-use` MCP server is available, and then lets Codex handle the native -MCP tool calls during Codex-mode turns. +`computer-use` MCP server is available, and then lets Codex own the native MCP +tool calls during Codex-mode turns. -For direct TryCua driver access outside the Codex marketplace flow, register -`cua-driver mcp` with `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`. -See [Codex Computer Use](/plugins/codex-computer-use) for the distinction -between Codex-owned Computer Use and direct MCP registration. - -Minimal config: - -```json5 -{ - plugins: { - entries: { - codex: { - enabled: true, - config: { - computerUse: { - autoInstall: true, - }, - }, - }, - }, - }, - agents: { - defaults: { - model: "openai/gpt-5.5", - }, - }, -} -``` - -The setup can be checked or installed from the command surface: - -- `/codex computer-use status` -- `/codex computer-use install` -- `/codex computer-use install --source ` -- `/codex computer-use install --marketplace-path ` - -Computer Use is macOS-specific and may require local OS permissions before the -Codex MCP server can control apps. If `computerUse.enabled` is true and the MCP -server is unavailable, Codex-mode turns fail before the thread starts instead of -silently running without the native Computer Use tools. See -[Codex Computer Use](/plugins/codex-computer-use) for marketplace choices, -remote catalog limits, status reasons, and troubleshooting. - -When `computerUse.autoInstall` is true, OpenClaw can register the standard -bundled Codex Desktop marketplace from -`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` if Codex -has not discovered a local marketplace yet. Use `/new` or `/reset` after -changing runtime or Computer Use config so existing sessions do not keep an old -PI or Codex thread binding. - -## Common recipes - -Local Codex with default stdio transport: - -```json5 -{ - plugins: { - entries: { - codex: { - enabled: true, - }, - }, - }, -} -``` - -Codex-only harness validation: - -```json5 -{ - models: { - providers: { - openai: { - agentRuntime: { - id: "codex", - }, - }, - }, - }, - agents: { - defaults: { - model: "openai/gpt-5.5", - }, - }, - plugins: { - entries: { - codex: { - enabled: true, - }, - }, - }, -} -``` - -Guardian-reviewed Codex approvals: - -```json5 -{ - plugins: { - entries: { - codex: { - enabled: true, - config: { - appServer: { - mode: "guardian", - approvalPolicy: "on-request", - approvalsReviewer: "auto_review", - sandbox: "workspace-write", - }, - }, - }, - }, - }, -} -``` - -Remote app-server with explicit headers: - -```json5 -{ - plugins: { - entries: { - codex: { - enabled: true, - config: { - appServer: { - transport: "websocket", - url: "ws://gateway-host:39175", - headers: { - "X-OpenClaw-Agent": "main", - }, - }, - }, - }, - }, - }, -} -``` - -Model switching stays OpenClaw-controlled. When an OpenClaw session is attached -to an existing Codex thread, the next turn sends the currently selected -OpenAI model, provider, approval policy, sandbox, and service tier to -app-server again. 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. - -## Codex command - -The bundled plugin registers `/codex` as an authorized slash command. It is -generic and works on any channel that supports OpenClaw text commands. - -Common forms: - -- `/codex status` shows live app-server connectivity, models, account, rate limits, MCP servers, and skills. -- `/codex models` lists live Codex app-server models. -- `/codex threads [filter]` lists recent Codex threads. -- `/codex resume ` attaches the current OpenClaw session to an existing Codex thread. -- `/codex compact` asks Codex app-server to compact the attached thread. -- `/codex review` starts Codex native review for the attached thread. -- `/codex diagnostics [note]` asks before sending Codex diagnostics feedback for the attached thread. -- `/codex computer-use status` checks the configured Computer Use plugin and MCP server. -- `/codex computer-use install` installs the configured Computer Use plugin and reloads MCP servers. -- `/codex account` shows account and rate-limit status. -- `/codex mcp` lists Codex app-server MCP server status. -- `/codex skills` lists Codex app-server skills. - -When Codex reports a usage-limit failure, OpenClaw includes the next -app-server reset time when Codex provided one. Use `/codex account` in the same -conversation to inspect the current account and rate-limit windows. - -### Common debugging workflow - -When a Codex-backed agent does something surprising in Telegram, Discord, Slack, -or another channel, start with the conversation where the problem happened: - -1. Run `/diagnostics bad tool choice after image upload` or another short note - that describes what you saw. -2. Approve the diagnostics request once. The approval creates the local Gateway - diagnostics zip and, because the session is using the Codex harness, also - sends the relevant Codex feedback bundle to OpenAI servers. -3. Copy the completed diagnostics reply into the bug report or support thread. - It includes the local bundle path, privacy summary, OpenClaw session ids, - Codex thread ids, and an `Inspect locally` line for each Codex thread. -4. If you want to debug the run yourself, run the printed `Inspect locally` - command in a terminal. It looks like `codex resume ` and opens the - native Codex thread so you can inspect the conversation, continue it locally, - or ask Codex why it chose a particular tool or plan. - -Use `/codex diagnostics [note]` only when you specifically want the Codex -feedback upload for the currently attached thread without the full OpenClaw -Gateway diagnostics bundle. For most support reports, `/diagnostics [note]` is -the better starting point because it ties the local Gateway state and Codex -thread ids together in one reply. See [Diagnostics export](/gateway/diagnostics) -for the full privacy model and group-chat behavior. - -Core OpenClaw also exposes owner-only `/diagnostics [note]` as the general -Gateway diagnostics command. Its approval prompt shows the sensitive-data -preamble, links to [Diagnostics Export](/gateway/diagnostics), and requests -`openclaw gateway diagnostics export --json` through explicit exec approval -every time. Do not approve diagnostics with an allow-all rule. After approval, -OpenClaw sends a pasteable report with the local bundle path and manifest -summary. When the active OpenClaw session is using the Codex harness, that -same approval also authorizes sending the relevant Codex feedback bundles to -OpenAI servers. The approval prompt says that Codex feedback will be sent, but -it does not list Codex session or thread ids before approval. - -If `/diagnostics` is invoked by an owner in a group chat, OpenClaw keeps the -shared channel clean: the group receives only a short notice, while the -diagnostics preamble, approval prompts, and Codex session/thread ids are sent to -the owner through the private approval route. If there is no private owner route, -OpenClaw refuses the group request and asks the owner to run it from a DM. - -The approved Codex upload calls Codex app-server `feedback/upload` and asks -app-server to include logs for each listed thread and spawned Codex subthreads -when available. The upload goes through Codex's normal feedback path to OpenAI -servers; if Codex feedback is disabled in that app-server, the command returns -the app-server error. The completed diagnostics reply lists the channels, -OpenClaw session ids, Codex thread ids, and local `codex resume ` -commands for the threads that were sent. If you deny or ignore the approval, -OpenClaw does not print those Codex ids. This upload does not replace the local -Gateway diagnostics export. - -`/codex resume` writes the same sidecar binding file that the harness uses for -normal turns. On the next message, OpenClaw resumes that Codex thread, passes the -currently selected OpenClaw model into app-server, and keeps extended history -enabled. - -### Inspect a Codex thread from the CLI - -The fastest way to understand a bad Codex run is often to open the native Codex -thread directly: - -```sh -codex resume -``` - -Use this when you notice a bug in a channel conversation and want to inspect the -problematic Codex session, continue it locally, or ask Codex why it made a -particular tool or reasoning choice. The easiest path is usually to run -`/diagnostics [note]` first: after you approve it, the completed report lists -each Codex thread and prints an `Inspect locally` command, for example -`codex resume `. You can copy that command directly into a terminal. - -You can also get a thread id from `/codex binding` for the current chat or -`/codex threads [filter]` for recent Codex app-server threads, then run the same -`codex resume` command in your shell. - -The command surface requires Codex app-server `0.125.0` or newer. Individual -control methods are reported as `unsupported by this Codex app-server` if a -future or custom app-server does not expose that JSON-RPC method. - -## Hook boundaries - -The Codex harness has three hook layers: - -| Layer | Owner | Purpose | -| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| OpenClaw plugin hooks | OpenClaw | Product/plugin compatibility across PI 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. | - -OpenClaw does not use project or global Codex `hooks.json` files to route -OpenClaw plugin behavior. For the supported native tool and permission bridge, -OpenClaw injects per-thread Codex config for `PreToolUse`, `PostToolUse`, -`PermissionRequest`, and `Stop`. When Codex app-server approvals are enabled -(`approvalPolicy` is not `"never"`), the default injected native hook config -omits `PermissionRequest` so Codex's app-server reviewer and OpenClaw's approval -bridge handle real escalations after review. Operators can still explicitly add -`permission_request` to `nativeHookRelay.events` when they need the compatibility -relay. Other Codex hooks such as `SessionStart` and `UserPromptSubmit` remain -Codex-level controls; they are not exposed as OpenClaw plugin hooks in the v1 -contract. - -For OpenClaw dynamic tools, OpenClaw executes the tool after Codex asks for the -call, so OpenClaw fires the plugin and middleware behavior it owns in the -harness adapter. For Codex-native tools, Codex owns the canonical tool record. -OpenClaw can mirror selected events, but it cannot rewrite the native Codex -thread unless Codex exposes that operation through app-server or native hook -callbacks. - -Compaction and LLM lifecycle projections come from Codex app-server -notifications and OpenClaw adapter state, not native Codex hook commands. -OpenClaw's `before_compaction`, `after_compaction`, `llm_input`, and -`llm_output` events are adapter-level observations, not byte-for-byte captures -of Codex's internal request or compaction payloads. - -Codex native `hook/started` and `hook/completed` app-server notifications are -projected as `codex_app_server.hook` agent events for trajectory and debugging. -They do not invoke OpenClaw plugin hooks. - -## V1 support contract - -Codex mode is not PI with a different model call underneath. Codex owns more of -the native model loop, and OpenClaw adapts its plugin and session surfaces -around that boundary. - -Supported in Codex runtime v1: - -| 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 builds prompt overlays and projects context into the Codex turn before starting or resuming the thread. | -| Context engine lifecycle | Supported | Assemble, ingest or after-turn maintenance, and context-engine compaction coordination run for Codex turns. | -| 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 the 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 the native hook relay | Codex `PreToolUse` and `PostToolUse` are relayed for committed native tool surfaces, including MCP payloads on Codex app-server `0.125.0` or newer. Blocking is supported; argument rewriting is not. | -| Native permission policy | Supported through Codex app-server approvals and the 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. | - -Not supported in Codex runtime v1: - -| 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 observes compaction start and completion, but does not receive a stable kept/dropped list, token delta, or summary payload. | Needs richer Codex compaction events. | -| Compaction intervention | Current OpenClaw compaction hooks are notification-level in Codex mode. | 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. | - -## Tools, media, and compaction +## Runtime boundaries The Codex harness changes the low-level embedded agent executor only. -OpenClaw still builds the tool list and receives dynamic tool results from the -harness. Text, images, video, music, TTS, approvals, and messaging-tool output -continue through the normal OpenClaw delivery path. +- OpenClaw dynamic tools are supported. Codex asks OpenClaw to execute those + tools, so OpenClaw remains in the execution path. +- Codex-native shell, patch, MCP, and native app tools are owned by Codex. + OpenClaw can observe or block selected native events through the supported + relay, but it does not rewrite native tool arguments. +- Codex owns native compaction. OpenClaw keeps a transcript mirror for channel + history, search, `/new`, `/reset`, and future model or harness switching. +- Media generation, media understanding, TTS, approvals, and messaging-tool + output continue through the matching OpenClaw provider/model settings. +- `tool_result_persist` applies to OpenClaw-owned transcript tool results, not + Codex-native tool result records. -The native hook relay is intentionally generic, but the v1 support contract is -limited to the Codex-native tool and permission paths that OpenClaw tests. In -the Codex runtime, that includes shell, patch, and MCP `PreToolUse`, -`PostToolUse`, and `PermissionRequest` payloads. Do not assume every future -Codex hook event is an OpenClaw plugin surface until the runtime contract names -it. - -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. -Codex app-server approval modes omit this native hook by default; this paragraph -applies when `permission_request` is explicitly included in -`nativeHookRelay.events` or a compatibility runtime installs it. -When an operator chooses `allow-always` for a Codex native permission request, -OpenClaw remembers that exact provider/session/tool input/cwd fingerprint for a -bounded session window. The remembered decision is intentionally exact-match -only: a changed command, arguments, tool payload, or cwd creates a fresh -approval. - -Codex MCP tool approval elicitations are routed through OpenClaw's plugin -approval flow when Codex marks `_meta.codex_approval_kind` as -`"mcp_tool_call"`. Codex `request_user_input` prompts are sent back to the -originating chat, and the next queued follow-up message answers that native -server request instead of being steered as extra context. Other MCP elicitation -requests still fail closed. - -Active-run queue steering maps onto Codex app-server `turn/steer`. With the -default `messages.queue.mode: "steer"`, OpenClaw batches queued chat messages -for the configured quiet window and sends them as one `turn/steer` request in -arrival order. Legacy `queue` mode sends separate `turn/steer` requests. Codex -review and manual compaction turns can reject same-turn steering, in which case -OpenClaw uses the followup queue when the selected mode allows fallback. See -[Steering queue](/concepts/queue-steering). - -When the selected model uses the Codex harness, native thread compaction is -delegated to Codex app-server. OpenClaw keeps a transcript mirror for channel -history, search, `/new`, `/reset`, and future model or harness switching. The -mirror includes the user prompt, final assistant text, and lightweight Codex -reasoning or plan records when the app-server emits them. Today, OpenClaw only -records native compaction start and completion signals. It does not yet expose a -human-readable compaction summary or an auditable list of which entries Codex -kept after compaction. - -Because Codex owns the canonical native thread, `tool_result_persist` does not -currently rewrite Codex-native tool result records. It only applies when -OpenClaw is writing an OpenClaw-owned session transcript tool result. - -Media generation does not require PI. Image, video, music, PDF, TTS, and media -understanding continue to use the matching provider/model settings such as -`agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel`, and -`messages.tts`. +For hook layers, supported V1 surfaces, native permission handling, queue +steering, Codex feedback upload mechanics, and compaction details, see +[Codex harness runtime](/plugins/codex-harness-runtime). ## Troubleshooting **Codex does not appear as a normal `/model` provider:** that is expected for new configs. Select an `openai/gpt-*` model, enable `plugins.entries.codex.enabled`, and check whether `plugins.allow` excludes -`codex`. Legacy `codex/*` refs remain compatibility aliases, not normal model -provider choices. +`codex`. -**OpenClaw uses PI instead of Codex:** make sure the model ref is `openai/gpt-*` -on the official OpenAI provider and that the Codex plugin is installed/enabled. -If you need a strict policy while testing, set provider/model -`agentRuntime.id: "codex"`. A forced Codex runtime fails instead of falling back -to PI. Once Codex app-server is selected, its failures surface directly. +**OpenClaw uses PI instead of Codex:** make sure the model ref is +`openai/gpt-*` on the official OpenAI provider and that the Codex plugin is +installed and enabled. If you need strict proof while testing, set provider or +model `agentRuntime.id: "codex"`. A forced Codex runtime fails instead of +falling back to PI. -**The app-server is rejected:** upgrade Codex so the app-server handshake -reports version `0.125.0` or newer. Same-version prereleases or build-suffixed -versions such as `0.125.0-alpha.2` or `0.125.0+custom` are rejected because the -stable `0.125.0` protocol floor is what OpenClaw tests. +**Legacy `openai-codex/*` config remains:** run `openclaw doctor --fix`. +Doctor rewrites legacy model refs to `openai/*`, removes stale session and +whole-agent runtime pins, and preserves existing auth-profile overrides. -**Model discovery is slow:** lower `plugins.entries.codex.config.discovery.timeoutMs` -or disable discovery. +**The app-server is rejected:** use Codex app-server `0.125.0` or newer. +Same-version prereleases or build-suffixed versions such as +`0.125.0-alpha.2` or `0.125.0+custom` are rejected because OpenClaw tests the +stable `0.125.0` protocol floor. + +**`/codex status` cannot connect:** check that the bundled `codex` plugin is +enabled, that `plugins.allow` includes it when an allowlist is configured, and +that any custom `appServer.command`, `url`, `authToken`, or headers are valid. + +**Model discovery is slow:** lower +`plugins.entries.codex.config.discovery.timeoutMs` or disable discovery. See +[Codex harness reference](/plugins/codex-harness-reference#model-discovery). **WebSocket transport fails immediately:** check `appServer.url`, `authToken`, -and that the remote app-server speaks the same Codex app-server protocol version. +headers, and that the remote app-server speaks the same Codex app-server +protocol version. -**A non-Codex model uses PI:** that is expected unless provider/model runtime +**A non-Codex model uses PI:** that is expected unless provider or model runtime policy routes it to another harness. Plain non-OpenAI provider refs stay on -their normal provider path in `auto` mode. If you force -`agentRuntime.id: "codex"` on a provider or model, matching embedded turns must -be Codex-supported OpenAI models. +their normal provider path in `auto` mode. **Computer Use is installed but tools do not run:** check `/codex computer-use status` from a fresh session. If a tool reports `Native hook relay unavailable`, use `/new` or `/reset`; if it persists, restart -the gateway to clear stale native hook registrations. If `computer-use.list_apps` -times out, restart Codex Computer Use or Codex Desktop and retry. +the gateway to clear stale native hook registrations. See +[Codex Computer Use](/plugins/codex-computer-use#troubleshooting). ## Related -- [Agent harness plugins](/plugins/sdk-agent-harness) +- [Codex harness reference](/plugins/codex-harness-reference) +- [Codex harness runtime](/plugins/codex-harness-runtime) +- [Native Codex plugins](/plugins/codex-native-plugins) +- [Codex Computer Use](/plugins/codex-computer-use) - [Agent runtimes](/concepts/agent-runtimes) - [Model providers](/concepts/model-providers) - [OpenAI provider](/providers/openai) -- [Status](/cli/status) +- [Agent harness plugins](/plugins/sdk-agent-harness) - [Plugin hooks](/plugins/hooks) -- [Configuration reference](/gateway/configuration-reference) +- [Diagnostics export](/gateway/diagnostics) +- [Status](/cli/status) - [Testing](/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/plugins/codex-native-plugins.md b/docs/plugins/codex-native-plugins.md new file mode 100644 index 00000000000..f1c84805cc0 --- /dev/null +++ b/docs/plugins/codex-native-plugins.md @@ -0,0 +1,188 @@ +--- +summary: "Configure migrated native Codex plugins for Codex-mode OpenClaw agents" +title: "Native Codex plugins" +read_when: + - You want Codex-mode OpenClaw agents to use native Codex plugins + - You are migrating source-installed openai-curated Codex plugins + - You are troubleshooting codexPlugins, app inventory, destructive actions, or plugin app diagnostics +--- + +Native Codex plugin support lets a Codex-mode OpenClaw agent use Codex +app-server's own app and plugin capabilities inside the same Codex thread that +handles the OpenClaw turn. + +OpenClaw does not translate Codex plugins into synthetic `codex_plugin_*` +OpenClaw dynamic tools. Plugin calls stay in the native Codex transcript, and +Codex app-server owns the app-backed MCP execution. + +Use this page after the base [Codex harness](/plugins/codex-harness) is working. + +## Requirements + +- The selected OpenClaw agent runtime must be the native Codex harness. +- `plugins.entries.codex.enabled` must be true. +- `plugins.entries.codex.config.codexPlugins.enabled` must be true. +- V1 supports only `openai-curated` plugins that migration observed as + source-installed in the source Codex home. +- The target Codex app-server must be able to see the expected marketplace, + plugin, and app inventory. + +`codexPlugins` has no effect on PI runs, normal OpenAI provider runs, ACP +conversation bindings, or other harnesses because those paths do not create +Codex app-server threads with native `apps` config. + +## Quickstart + +Preview migration from the source Codex home: + +```bash +openclaw migrate codex --dry-run +``` + +Apply the migration when the plan looks right: + +```bash +openclaw migrate apply codex --yes +``` + +Migration writes explicit `codexPlugins` entries for eligible plugins and calls +Codex app-server `plugin/install` for selected plugins. A typical migrated +config looks like this: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + codexPlugins: { + enabled: true, + allow_destructive_actions: false, + plugins: { + "google-calendar": { + enabled: true, + marketplaceName: "openai-curated", + pluginName: "google-calendar", + }, + }, + }, + }, + }, + }, + }, +} +``` + +After changing `codexPlugins`, use `/new`, `/reset`, or restart the gateway so +future Codex harness sessions start with the updated app set. + +## How native plugin setup works + +The integration has three separate states: + +- Installed: Codex has the local plugin bundle in the target app-server runtime. +- Enabled: OpenClaw config is willing to make the plugin available to Codex + harness turns. +- Accessible: Codex app-server confirms the plugin's app entries are available + for the active account and can be mapped to the migrated plugin identity. + +Migration is the durable install/eligibility step. Runtime app inventory is the +accessibility check. Codex harness session setup then computes a restrictive +thread app config for the enabled and accessible plugin apps. + +Thread app config is computed when OpenClaw establishes a Codex harness session +or replaces a stale Codex thread binding. It is not recomputed on every turn. + +## V1 support boundary + +V1 is intentionally narrow: + +- Only `openai-curated` plugins that were already installed in the source Codex + app-server inventory are migration-eligible. +- Migration writes explicit plugin identities with `marketplaceName` and + `pluginName`; it does not write local `marketplacePath` cache paths. +- `codexPlugins.enabled` is the global enablement switch. +- There is no `plugins["*"]` wildcard and no config key that grants arbitrary + install authority. +- Unsupported marketplaces, cached plugin bundles, hooks, and Codex config files + are preserved in the migration report for manual review. + +## App inventory and ownership + +OpenClaw reads Codex app inventory through app-server `app/list`, caches it for +one hour, and refreshes stale or missing entries asynchronously. + +A plugin app is exposed only when OpenClaw can map it back to the migrated +plugin through stable ownership: + +- exact app id from plugin detail +- known MCP server name +- unique stable metadata + +Display-name-only or ambiguous ownership is excluded until the next inventory +refresh proves ownership. + +## Thread app config + +OpenClaw injects a restrictive `config.apps` patch for the Codex thread: +`_default` is disabled and only apps owned by enabled migrated plugins are +enabled. + +OpenClaw sets app-level `destructive_enabled` from the effective global or +per-plugin `allow_destructive_actions` policy and lets Codex enforce +destructive tool metadata from its native app tool annotations. The `_default` +app config is disabled with `open_world_enabled: false`. Enabled plugin apps +are emitted with `open_world_enabled: true`; OpenClaw does not expose a separate +plugin open-world policy knob and does not maintain per-plugin destructive +tool-name deny lists. + +Tool approval mode is prompted by default for plugin apps because OpenClaw does +not have an interactive app-elicitation UI in this same-thread path. + +## Destructive action policy + +Destructive plugin elicitations fail closed by default: + +- Global `allow_destructive_actions` defaults to `false`. +- Per-plugin `allow_destructive_actions` overrides the global policy for that + plugin. +- When policy is `false`, OpenClaw returns a deterministic decline. +- When policy is `true`, OpenClaw auto-accepts only safe schemas it can map to + an approval response, such as a boolean approve field. +- Missing plugin identity, ambiguous ownership, a missing turn id, a wrong turn + id, or an unsafe elicitation schema declines instead of prompting. + +## Troubleshooting + +**`auth_required`:** migration installed the plugin, but one of its apps still +needs authentication. The explicit plugin entry is written disabled until you +reauthorize and enable it. + +**`marketplace_missing` or `plugin_missing`:** the target Codex app-server +cannot see the expected `openai-curated` marketplace or plugin. Rerun migration +against the target runtime or inspect Codex app-server plugin status. + +**`app_inventory_missing` or `app_inventory_stale`:** app readiness came from an +empty or stale cache. OpenClaw schedules an async refresh and excludes plugin +apps until ownership and readiness are known. + +**`app_ownership_ambiguous`:** app inventory only matched by display name, so +the app is not exposed to the Codex thread. + +**Config changed but the agent cannot see the plugin:** use `/new`, `/reset`, or +restart the gateway. Existing Codex thread bindings keep the app config they +started with until OpenClaw establishes a new harness session or replaces a +stale binding. + +**Destructive action is declined:** check the global and per-plugin +`allow_destructive_actions` values. Even when policy is true, unsafe elicitation +schemas and ambiguous plugin identity still fail closed. + +## Related + +- [Codex harness](/plugins/codex-harness) +- [Codex harness reference](/plugins/codex-harness-reference) +- [Codex harness runtime](/plugins/codex-harness-runtime) +- [Configuration reference](/gateway/configuration-reference#codex-harness-plugin-config) +- [Migrate CLI](/cli/migrate) diff --git a/docs/plugins/reference/codex.md b/docs/plugins/reference/codex.md index 88f4bdcaafa..61d12776fce 100644 --- a/docs/plugins/reference/codex.md +++ b/docs/plugins/reference/codex.md @@ -20,4 +20,7 @@ providers: codex; contracts: mediaUnderstandingProviders, migrationProviders ## Related docs -- [codex](/plugins/codex-harness) +- [Codex harness](/plugins/codex-harness) +- [Codex harness reference](/plugins/codex-harness-reference) +- [Codex harness runtime](/plugins/codex-harness-runtime) +- [Native Codex plugins](/plugins/codex-native-plugins) diff --git a/docs/tools/acp-agents.md b/docs/tools/acp-agents.md index 2ecfa97a5c1..e1743ebe0fa 100644 --- a/docs/tools/acp-agents.md +++ b/docs/tools/acp-agents.md @@ -180,7 +180,7 @@ Quick `/acp` flow from chat: arguments or rewrite Codex thread records. Use explicit ACP only when you want the ACP runtime/session model. The embedded Codex support boundary is documented in the - [Codex harness v1 support contract](/plugins/codex-harness#v1-support-contract). + [Codex harness v1 support contract](/plugins/codex-harness-runtime#v1-support-contract). @@ -840,6 +840,7 @@ permission modes, see - [Agent send](/tools/agent-send) - [CLI Backends](/gateway/cli-backends) - [Codex harness](/plugins/codex-harness) +- [Codex harness runtime](/plugins/codex-harness-runtime) - [Multi-agent sandbox tools](/tools/multi-agent-sandbox-tools) - [`openclaw acp` (bridge mode)](/cli/acp) - [Sub-agents](/tools/subagents) diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index 776839a88d6..6268d0b74b1 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -717,7 +717,7 @@ hook surface. Plugins can block native Codex tools through `before_tool_call`, observe results through `after_tool_call`, and participate in Codex `PermissionRequest` approvals. The bridge does not rewrite Codex-native tool arguments yet. The exact Codex runtime support boundary lives in the -[Codex harness v1 support contract](/plugins/codex-harness#v1-support-contract). +[Codex harness v1 support contract](/plugins/codex-harness-runtime#v1-support-contract). For full typed hook behavior, see [SDK overview](/plugins/sdk-overview#hook-decision-semantics).