From 7e2a22b9f60147350be2d19d92ff3af93e6fc1d4 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Mon, 27 Apr 2026 23:48:40 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@3f94f25a3c7a33a046d5b922c653d0b3b9be51ea --- .openclaw-sync/source.json | 4 +- docs/plugins/codex-harness.md | 80 ++++++++++++++++++++++++++--------- docs/providers/openai.md | 20 +++++++++ 3 files changed, 83 insertions(+), 21 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 7f6e78ac8..f3bb9a760 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "f3d53ce22c235378a69ba162adb0eaf1d94ed3c7", - "syncedAt": "2026-04-27T23:40:16.961Z" + "sha": "3f94f25a3c7a33a046d5b922c653d0b3b9be51ea", + "syncedAt": "2026-04-27T23:47:18.061Z" } diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index ed8eb98fb..1e1e7cf5b 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -179,15 +179,15 @@ Codex after changing config. - 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. +- Codex auth available to the app-server process or to OpenClaw's Codex auth + bridge. 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 `OPENAI_API_KEY`, plus -optional Codex CLI files such as `~/.codex/auth.json` and -`~/.codex/config.toml`. Use the same auth material your local Codex app-server -uses. +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. ## Minimal config @@ -508,22 +508,64 @@ 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: + +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. +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. + 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. | -| `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. | +| `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. | Environment overrides remain available for local testing: diff --git a/docs/providers/openai.md b/docs/providers/openai.md index 198db5646..e4e83e088 100644 --- a/docs/providers/openai.md +++ b/docs/providers/openai.md @@ -285,6 +285,26 @@ Choose your preferred auth method and follow the setup steps. +## Native Codex app-server auth + +The native Codex app-server harness uses `openai/*` model refs plus +`agentRuntime.id: "codex"`, but its auth is still account-based. OpenClaw +selects auth in this order: + +1. An explicit OpenClaw `openai-codex` auth profile bound to the agent. +2. The app-server's existing account, such as a local Codex CLI ChatGPT sign-in. +3. For local stdio app-server launches only, `CODEX_API_KEY`, then + `OPENAI_API_KEY`, when the app-server reports no account and still requires + OpenAI auth. + +That means a local ChatGPT/Codex subscription sign-in is not replaced just +because the gateway process also has `OPENAI_API_KEY` for direct OpenAI models +or embeddings. Env API-key fallback is only the local stdio no-account path; it +is not sent to WebSocket app-server connections. When a subscription-style Codex +profile is selected, OpenClaw also keeps `CODEX_API_KEY` and `OPENAI_API_KEY` +out of the spawned stdio app-server child and sends the selected credentials +through the app-server login RPC. + ## Image generation The bundled `openai` plugin registers image generation through the `image_generate` tool.