diff --git a/CHANGELOG.md b/CHANGELOG.md index b4d3915707f..642bc94fd97 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ Docs: https://docs.openclaw.ai ### Fixes +- Docs/Codex harness: clarify that per-agent `CODEX_HOME` isolates `~/.codex` while inherited `HOME` intentionally keeps `.agents` discovery and subprocess user-home state available. - CLI tables: preserve muted/color styling on wrapped continuation lines after multiline cells, keeping `openclaw plugins list` descriptions readable. - iOS: restore first-use Contacts, Calendar, and Reminders permission prompts and add Privacy & Access status/actions in Settings. Thanks @BunsDev. - Canvas: return not found for malformed percent-encoded Canvas/A2UI/document asset paths and keep decoded parent traversal blocked before path normalization. diff --git a/docs/cli/migrate.md b/docs/cli/migrate.md index 56384f7b4b5..ecc612874f8 100644 --- a/docs/cli/migrate.md +++ b/docs/cli/migrate.md @@ -123,9 +123,10 @@ 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 a per-agent `CODEX_HOME`, so they do not read your personal Codex -CLI state by default, while subprocesses still inherit the normal process -`HOME` unless the app-server launch explicitly overrides it. +launches use a per-agent `CODEX_HOME`, so they do not read your personal +`~/.codex` by default. The normal process `HOME` is still inherited, so Codex +can see shared `$HOME/.agents/*` skills/plugin marketplace entries and +subprocesses can find user-home config and tokens. Running `openclaw migrate codex` in an interactive terminal previews the full plan, then opens checkbox selectors before the final apply confirmation. Skill diff --git a/docs/plugins/codex-harness-reference.md b/docs/plugins/codex-harness-reference.md index 525393e98c6..45ac77e8936 100644 --- a/docs/plugins/codex-harness-reference.md +++ b/docs/plugins/codex-harness-reference.md @@ -166,18 +166,23 @@ 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. +Stdio app-server launches inherit OpenClaw's process environment by default. +OpenClaw owns the Codex app-server account bridge and sets `CODEX_HOME` to a +per-agent directory under that agent's OpenClaw state. That keeps Codex config, +accounts, plugin cache/data, and thread state scoped to the OpenClaw agent +instead of leaking in from the operator's personal `~/.codex` home. + +OpenClaw does not rewrite `HOME` for normal local app-server launches. Codex-run +subprocesses such as `openclaw`, `gh`, `git`, cloud CLIs, and shell commands see +the normal process home and can find user-home config and tokens. Codex may also +discover `$HOME/.agents/skills` and `$HOME/.agents/plugins/marketplace.json`; +that `.agents` discovery is intentionally shared with the operator home and is +separate from isolated `~/.codex` state. 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: +plugin registry and skill loader. Personal Codex `~/.codex` assets do not. If +you have useful Codex CLI skills or plugins from a Codex home that should become +part of an OpenClaw agent, inventory them explicitly: ```bash openclaw migrate codex --dry-run @@ -205,8 +210,9 @@ If a deployment needs additional environment isolation, add those variables to ``` `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. +OpenClaw removes `CODEX_HOME` and `HOME` from this list during local launch +normalization: `CODEX_HOME` stays per-agent, and `HOME` stays inherited so +subprocesses can use normal user-home state. ## Dynamic tools diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index d570ba47a4e..b4eb07e3ba6 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -424,6 +424,13 @@ time when Codex reports one and tries the next ordered auth profile for the same Codex run. When the reset time passes, the subscription profile becomes eligible again without changing the selected `openai/gpt-*` model or Codex runtime. +For local stdio app-server launches, OpenClaw sets `CODEX_HOME` to a per-agent +directory so Codex config, auth/account files, plugin cache/data, and native +thread state do not read or write the operator's personal `~/.codex` by +default. OpenClaw preserves the normal process `HOME`; Codex-run subprocesses +can still find user-home config and tokens, and Codex may discover shared +`$HOME/.agents/skills` and `$HOME/.agents/plugins/marketplace.json` entries. + If a deployment needs additional environment isolation, add those variables to `appServer.clearEnv`: @@ -445,6 +452,9 @@ If a deployment needs additional environment isolation, add those variables to ``` `appServer.clearEnv` only affects the spawned Codex app-server child process. +OpenClaw removes `CODEX_HOME` and `HOME` from this list during local launch +normalization: `CODEX_HOME` stays per-agent, and `HOME` stays inherited so +subprocesses can use normal user-home state. Codex dynamic tools default to `searchable` loading. OpenClaw does not expose dynamic tools that duplicate Codex-native workspace operations: `read`, `write`, @@ -480,7 +490,7 @@ Supported `appServer` fields: | `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. | +| `clearEnv` | `[]` | Extra environment variable names removed from the spawned stdio app-server process after OpenClaw builds its inherited environment. OpenClaw keeps per-agent `CODEX_HOME` and inherited `HOME` for 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. | diff --git a/docs/tools/skills.md b/docs/tools/skills.md index c9084a2dcf1..b21e06050d1 100644 --- a/docs/tools/skills.md +++ b/docs/tools/skills.md @@ -31,9 +31,12 @@ 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 +per-agent Codex homes, so skills in the operator's personal `~/.codex/skills` +are not loaded implicitly. Codex-native `.agents` discovery uses inherited +`HOME` separately; OpenClaw's own skill roots above already include +`~/.agents/skills`. Use `openclaw migrate codex --dry-run` to inventory skills +from the Codex home, then `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.