LLM/moltbot
1
0
Fork 0
mirror of https://github.com/moltbot/moltbot.git synced 2026-05-13 15:47:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: reorganize Codex harness docs (#80029)

Browse Source 
* docs: reorganize codex harness docs

* docs: address codex harness review findings

* docs: move codex references to reference nav

* docs: add codex topic configuration section
This commit is contained in:
Kevin Lin
2026-05-09 19:02:50 -07:00
committed by GitHub
parent 28cc60f13c
commit ce0584af89
14 changed files with 1322 additions and 991 deletions
Download Patch File Download Diff File Expand all files Collapse all files

234
.agents/skills/openclaw-docs/SKILL.md Normal file
View File

@@ -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 `<API_KEY>` or `<CUSTOMER_ID>`.
- 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.

1
.gitignore vendored
View File

@@ -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/

28
docs/.i18n/glossary.zh-CN.json
View File

@@ -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）"

5
docs/concepts/agent-runtimes.md
View File

@@ -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)

8
docs/docs.json
View File

@@ -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": [

5
docs/gateway/configuration-reference.md
View File

@@ -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

2
docs/gateway/diagnostics.md
View File

@@ -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 <thread-id>` 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

376
docs/plugins/codex-harness-reference.md Normal file
View File

@@ -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)

212
docs/plugins/codex-harness-runtime.md Normal file
View File

@@ -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 <thread-id>` 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)

1244
docs/plugins/codex-harness.md
View File

File diff suppressed because it is too large Load Diff

188
docs/plugins/codex-native-plugins.md Normal file
View File

@@ -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)

5
docs/plugins/reference/codex.md
View File

@@ -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)

3
docs/tools/acp-agents.md
View File

@@ -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).
</Accordion>
<Accordion title="Model / provider / runtime selection cheat sheet">
@@ -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)

2
docs/tools/plugin.md
View File

@@ -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).