From 394409c295bc06f8c4bdf200e8705b17826f828e Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Thu, 30 Apr 2026 19:52:04 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@027ea5f08bd9c93b91e4ddc25edc842bab61bbd0 --- .openclaw-sync/source.json | 4 +- docs/cli/doctor.md | 1 + docs/cli/migrate.md | 46 ++++++++++++++++++++++- docs/concepts/agent-workspace.md | 1 + docs/gateway/security/index.md | 2 + docs/plugins/codex-harness.md | 63 ++++++++++++++++++++++---------- docs/tools/skills.md | 8 ++++ 7 files changed, 103 insertions(+), 22 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 35d415370..d581a3a61 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "54e6e3d7daf5d0d857edf756b35628a29d11c7f5", - "syncedAt": "2026-04-30T18:23:48.767Z" + "sha": "027ea5f08bd9c93b91e4ddc25edc842bab61bbd0", + "syncedAt": "2026-04-30T19:50:09.352Z" } diff --git a/docs/cli/doctor.md b/docs/cli/doctor.md index 0d4f946e6..24694edfe 100644 --- a/docs/cli/doctor.md +++ b/docs/cli/doctor.md @@ -52,6 +52,7 @@ Notes: - Repeat `doctor --fix` runs no longer report/apply Talk normalization when the only difference is object key order. - Doctor includes a memory-search readiness check and can recommend `openclaw configure --section model` when embedding credentials are missing. - Doctor warns when no command owner is configured. The command owner is the human operator account allowed to run owner-only commands and approve dangerous actions. DM pairing only lets someone talk to the bot; if you approved a sender before first-owner bootstrap existed, set `commands.ownerAllowFrom` explicitly. +- Doctor warns when Codex-mode agents are configured and personal Codex CLI assets exist in the operator's Codex home. Local Codex app-server launches use isolated per-agent homes, so use `openclaw migrate codex --dry-run` to inventory assets that should be promoted deliberately. - If sandbox mode is enabled but Docker is unavailable, doctor reports a high-signal warning with remediation (`install Docker` or `openclaw config set agents.defaults.sandbox.mode off`). - If `gateway.auth.token`/`gateway.auth.password` are SecretRef-managed and unavailable in the current command path, doctor reports a read-only warning and does not write plaintext fallback credentials. - If channel SecretRef inspection fails in a fix path, doctor continues and reports a warning instead of exiting early. diff --git a/docs/cli/migrate.md b/docs/cli/migrate.md index fd79b596a..cdf2db4a1 100644 --- a/docs/cli/migrate.md +++ b/docs/cli/migrate.md @@ -8,7 +8,7 @@ title: "Migrate" # `openclaw migrate` -Import state from another agent system through a plugin-owned migration provider. Bundled providers cover [Claude](/install/migrating-claude) and [Hermes](/install/migrating-hermes); third-party plugins can register additional providers. +Import state from another agent system through a plugin-owned migration provider. Bundled providers cover Codex CLI state, [Claude](/install/migrating-claude), and [Hermes](/install/migrating-hermes); third-party plugins can register additional providers. For user-facing walkthroughs, see [Migrating from Claude](/install/migrating-claude) and [Migrating from Hermes](/install/migrating-hermes). The [migration hub](/install/migrating) lists all paths. @@ -19,8 +19,12 @@ For user-facing walkthroughs, see [Migrating from Claude](/install/migrating-cla ```bash openclaw migrate list openclaw migrate claude --dry-run +openclaw migrate codex --dry-run +openclaw migrate codex --skill gog-vault77-google-workspace openclaw migrate hermes --dry-run openclaw migrate hermes +openclaw migrate apply codex --yes --skill gog-vault77-google-workspace +openclaw migrate apply codex --yes openclaw migrate apply claude --yes openclaw migrate apply hermes --yes openclaw migrate apply hermes --include-secrets --yes @@ -47,6 +51,9 @@ openclaw onboard --import-from hermes --import-source ~/.hermes Skip the confirmation prompt. Required in non-interactive mode. + + Select one skill copy item by skill name or item id. Repeat the flag to migrate multiple skills. When omitted, interactive Codex migrations show a checkbox selector and non-interactive migrations keep all planned skills. + Skip the pre-apply backup. Requires `--force` when local OpenClaw state exists. @@ -99,6 +106,43 @@ For a user-facing walkthrough, see [Migrating from Claude](/install/migrating-cl Claude hooks, permissions, environment defaults, local memory, path-scoped rules, subagents, caches, plans, and project history are preserved in the migration report or reported as manual-review items. OpenClaw does not execute hooks, copy broad allowlists, or import OAuth/Desktop credential state automatically. +## Codex provider + +The bundled Codex provider detects Codex CLI state at `~/.codex` by default, or +at `CODEX_HOME` when that environment variable is set. Use `--from ` to +inventory a specific Codex home. + +Use this provider when moving to the OpenClaw Codex harness and you want to +promote useful personal Codex CLI assets deliberately. Local Codex app-server +launches use per-agent `CODEX_HOME` and `HOME` directories, so they do not read +your personal Codex CLI state by default. + +Running `openclaw migrate codex` in an interactive terminal previews the full +plan, then opens a checkbox selector for skill copy items before the final +apply confirmation. All skills start selected; uncheck any skill you do not want +copied into this agent. For scripted or exact runs, pass `--skill ` once +per skill, for example: + +```bash +openclaw migrate codex --dry-run --skill gog-vault77-google-workspace +openclaw migrate apply codex --yes --skill gog-vault77-google-workspace +``` + +### What Codex imports + +- Codex CLI skill directories under `$CODEX_HOME/skills`, excluding Codex's + `.system` cache. +- Personal AgentSkills under `$HOME/.agents/skills`, copied into the current + OpenClaw agent workspace when you want per-agent ownership. + +### Manual-review Codex state + +Codex native plugins, `config.toml`, and native `hooks/hooks.json` are not +activated automatically. Plugins may expose MCP servers, apps, hooks, or other +executable behavior, so the provider reports them for review instead of loading +them into OpenClaw. Config and hook files are copied into the migration report +for manual review. + ## Hermes provider The bundled Hermes provider detects state at `~/.hermes` by default. Use `--from ` when Hermes lives elsewhere. diff --git a/docs/concepts/agent-workspace.md b/docs/concepts/agent-workspace.md index aba67a7e7..f84683159 100644 --- a/docs/concepts/agent-workspace.md +++ b/docs/concepts/agent-workspace.md @@ -108,6 +108,7 @@ These live under `~/.openclaw/` and should NOT be committed to the workspace rep - `~/.openclaw/openclaw.json` (config) - `~/.openclaw/agents//agent/auth-profiles.json` (model auth profiles: OAuth + API keys) +- `~/.openclaw/agents//agent/codex-home/` (per-agent Codex runtime account, config, skills, plugins, and native thread state) - `~/.openclaw/credentials/` (channel/provider state plus legacy OAuth import data) - `~/.openclaw/agents//sessions/` (session transcripts + metadata) - `~/.openclaw/skills/` (managed skills) diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index add1748f2..985113574 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -236,6 +236,7 @@ Use this when auditing access or deciding what to back up: - `~/.openclaw/credentials/-allowFrom.json` (default account) - `~/.openclaw/credentials/--allowFrom.json` (non-default accounts) - **Model auth profiles**: `~/.openclaw/agents//agent/auth-profiles.json` +- **Codex runtime state**: `~/.openclaw/agents//agent/codex-home/` - **File-backed secrets payload (optional)**: `~/.openclaw/secrets.json` - **Legacy OAuth import**: `~/.openclaw/credentials/oauth.json` @@ -965,6 +966,7 @@ Assume anything under `~/.openclaw/` (or `$OPENCLAW_STATE_DIR/`) may contain sec - `openclaw.json`: config may include tokens (gateway, remote gateway), provider settings, and allowlists. - `credentials/**`: channel credentials (example: WhatsApp creds), pairing allowlists, legacy OAuth imports. - `agents//agent/auth-profiles.json`: API keys, token profiles, OAuth tokens, and optional `keyRef`/`tokenRef`. +- `agents//agent/codex-home/**`: per-agent Codex app-server account, config, skills, plugins, native thread state, and diagnostics. - `secrets.json` (optional): file-backed secret payload used by `file` SecretRef providers (`secrets.providers`). - `agents//agent/auth.json`: legacy compatibility file. Static `api_key` entries are scrubbed when discovered. - `agents//sessions/**`: session transcripts (`*.jsonl`) + routing metadata (`sessions.json`) that can contain private messages and tool output. diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index d6223cf81..1db06c527 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -180,7 +180,10 @@ Codex after changing config. 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. + 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. @@ -511,11 +514,33 @@ For an already-running app-server, use WebSocket transport: ``` Stdio app-server launches inherit OpenClaw's process environment by default, -but OpenClaw owns the Codex app-server account bridge. Auth is selected in this -order: +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 +``` + +The Codex migration provider copies skills into the current OpenClaw agent +workspace. Codex native plugins, hooks, and config files are reported or archived +for manual review instead of being activated automatically, because they can +execute commands, expose MCP servers, or carry credentials. + +Auth is selected in this order: 1. An explicit OpenClaw Codex auth profile for the agent. -2. The app-server's existing account, such as a local Codex CLI ChatGPT sign-in. +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. @@ -553,21 +578,21 @@ If a deployment needs additional environment isolation, add those variables to 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. | -| `requestTimeoutMs` | `60000` | Timeout for app-server control-plane calls. | -| `mode` | `"yolo"` | Preset for YOLO or guardian-reviewed execution. | -| `approvalPolicy` | `"never"` | Native Codex approval policy sent to thread start/resume/turn. | -| `sandbox` | `"danger-full-access"` | Native Codex sandbox mode sent to thread start/resume. | -| `approvalsReviewer` | `"user"` | Use `"auto_review"` to let Codex review native approval prompts. `guardian_subagent` remains a legacy alias. | -| `serviceTier` | unset | Optional Codex app-server service tier: `"fast"`, `"flex"`, or `null`. Invalid legacy values are ignored. | +| 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. | +| `mode` | `"yolo"` | Preset for YOLO or guardian-reviewed execution. | +| `approvalPolicy` | `"never"` | Native Codex approval policy sent to thread start/resume/turn. | +| `sandbox` | `"danger-full-access"` | Native Codex sandbox mode sent to thread start/resume. | +| `approvalsReviewer` | `"user"` | Use `"auto_review"` to let Codex review native approval prompts. `guardian_subagent` remains a legacy alias. | +| `serviceTier` | unset | Optional Codex app-server service tier: `"fast"`, `"flex"`, or `null`. Invalid legacy values are ignored. | OpenClaw-owned dynamic tool calls are bounded independently from `appServer.requestTimeoutMs`: each Codex `item/tool/call` request must receive diff --git a/docs/tools/skills.md b/docs/tools/skills.md index 33e01eed8..37f1e0dc5 100644 --- a/docs/tools/skills.md +++ b/docs/tools/skills.md @@ -29,6 +29,14 @@ OpenClaw loads skills from these sources, **highest precedence first**: If a skill name conflicts, the highest source wins. +Codex CLI's native `$CODEX_HOME/skills` directory is not one of these OpenClaw +skill roots. In Codex harness mode, local app-server launches use isolated +per-agent Codex homes, so personal Codex CLI skills are not loaded implicitly. +Use `openclaw migrate codex --dry-run` to inventory them and +`openclaw migrate codex` to choose skill directories with an interactive +checkbox prompt before copying them into the current OpenClaw agent workspace. +For non-interactive runs, repeat `--skill ` for the exact skills to copy. + ## Per-agent vs shared skills In **multi-agent** setups each agent has its own workspace: