Codex app-server transport

How OpenClaw starts and reaches the Codex app-server, and every appServer field. Part of the Codex harness reference; Where each section moved lists every section.

App-server transport

For ordinary harness turns, OpenClaw starts the managed Codex binary shipped with the official plugin (currently @openai/codex 0.153.4):

codex app-server --listen stdio://

This keeps the app-server version tied to the official codex plugin instead of whichever separate Codex CLI happens to be installed locally. OpenClaw resolves @openai/codex/bin/codex.js from the loader-selected plugin root using Node package resolution, including npm-hoisted and pnpm-linked dependencies. It does not search .bin shims or global PATH for managed startup. On Windows, Node runs the same package entrypoint without requiring a codex.cmd shim. Set appServer.command only when you intentionally want a different executable. Ordinary managed turns with the default isolated agent home prefer this pinned package even when a macOS desktop bundle is installed. When Computer Use is enabled, or when homeScope is "user" and can load native Computer Use state, managed startup instead prefers the desktop app binary that owns the required macOS permissions. The same desktop-first rule applies when an isolated agent home's effective Codex config enables native Computer Use. If no desktop app bundle is installed, OpenClaw falls back to the pinned package binary.

Before cutting over a staged OpenClaw package, run the opt-in managed-binary check against the candidate installation:

openclaw doctor --lint --only codex/managed-app-server --json

The check is read-only. For every configured Codex agent it applies the same final command selection as a live harness turn, then verifies that a selected package-owned native binary exists and reports the plugin's exact pinned version. A selected Codex Desktop binary, an explicit custom command, and a remote app-server are outside this package check. The command exits nonzero on an error-level finding, so a deployer can reject the candidate before cutover without changing Codex state or app-server settings.

Executable handoff and native-config fencing coordinate clients inside one running Gateway process. Restart the Gateway after another process changes the native Codex plugin config.

Supervision resolves a separate connection. With no explicit appServer connection settings, it uses managed stdio with homeScope: "user"; the ordinary harness remains managed stdio with homeScope: "agent". Explicit connection settings are honored by both paths. Set homeScope: "user" explicitly when the ordinary harness should share $CODEX_HOME (or ~/.codex) with native clients. A private supervised binding uses the supervision connection regardless of the ordinary harness default. Independent App Server processes retain separate live status and approval state.

For non-production testing against an already-running app-server, WebSocket transport is available:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            transport: "websocket",            url: "ws://gateway-host:39175",            authToken: "${CODEX_APP_SERVER_TOKEN}",            requestTimeoutMs: 60000,          },        },      },    },  },}

Codex classifies WebSocket transport as experimental and unsupported. Prefer managed stdio or the local Unix control socket for production workloads.

appServer fields:

appServer.args accepts an array (recommended) or a quoted argument string. OPENCLAW_CODEX_APP_SERVER_ARGS uses the same string parsing on every platform: single and double quotes group words, backslashes and # stay literal, and an unfinished quote groups the remaining text. This preserves the string grammar shipped in v2026.9.1; strings do not use shell escaping.

Use array entries for values containing embedded quotes, such as 'model="gpt-5.6-luna"'. For a directory containing a literal backslash, both forms below pass the same path to Codex:

args: "app-server --listen stdio:// -c log_dir=/tmp/openclaw\\logs"

args: ["app-server", "--listen", "stdio://", "-c", "log_dir=/tmp/openclaw\\logs"]

The \\ in JSON5 encodes one backslash. Array entries preserve embedded quotes and backslashes, but surrounding whitespace is trimmed and empty entries are omitted. Strings also omit empty quoted arguments. Account for these limits before converting existing strings to arrays.

appServer.serviceTier is used only when no shared Fast-mode run control is supplied. On Codex harness turns, shared Fast on sends priority, Fast off sends null to clear the OpenClaw-owned tier, and auto decides for each model call. /codex fast off is separate: it persists flex in the bound native conversation preference for later conversation-bound turns and does not change the shared OpenClaw session policy. These values describe native configuration and preference state, not observed provider routing.

appServer.networkProxy is explicit because it changes the Codex sandbox contract. When enabled, OpenClaw also sets features.network_proxy.enabled and default_permissions in the Codex thread config so the generated permission profile can start Codex-managed networking. OpenClaw generates a collision-resistant openclaw-network-<fingerprint> profile name from the profile body by default; use profileName only when a stable local name is required.

export default {  plugins: {    entries: {      codex: {        config: {          appServer: {            sandbox: "workspace-write",            networkProxy: {              enabled: true,              domains: {                "api.openai.com": "allow",                "blocked.example.com": "deny",              },              allowUpstreamProxy: true,              proxyUrl: "http://127.0.0.1:3128",            },          },        },      },    },  },};

If the normal app-server runtime would be danger-full-access, enabling networkProxy uses workspace-style filesystem access for the generated permission profile instead. Codex-managed network enforcement is sandboxed networking, so a full-access profile would not protect outbound traffic.

The plugin manages stable Codex app-server 0.153.4. Explicit custom executables, remote app-servers, and macOS desktop binaries must report a parseable semantic version of 0.149.0 or newer. Older, malformed, and unversioned handshakes are rejected. Newer versions log a compatibility warning and continue through normal runtime and capability validation.

OpenClaw treats non-loopback WebSocket app-server URLs as remote and requires identity-bearing WebSocket auth through appServer.authToken or an Authorization header. appServer.authToken and each appServer.headers.* value can be a SecretInput; the secrets runtime resolves SecretRefs and env shorthand before OpenClaw builds app-server start options, and unresolved structured SecretRefs fail before any token or header is sent.

When native Codex plugins are configured, OpenClaw caches one runtime-and-workspace-scoped plugin/installed snapshot. This snapshot covers installed plugins from Codex-discovered marketplaces, including disabled ownership; plugin/read resolves only exact configured plugin identities. Failed or incomplete installed snapshots are never cached. /codex plugins available queries plugin/list for the current conversation workspace, while /codex plugins install <plugin>@<marketplace> installs only after an owner or operator.admin explicitly authorizes that plugin. Existing explicitly configured curated plugins retain their automatic recovery path. The model's plugin-discovery tool cannot install, enable, or authenticate a plugin.

app/installed reports installed app runtime state, and app/read returns authenticated metadata for at most 100 requested app IDs per call. OpenClaw force-refreshes the first cold installed snapshot and consolidates successful curated installations into one app-inventory refresh. Later cached reads do not force repeated connector refreshes.

Deny-by-default Codex app policy is evaluated per thread, so an explicitly allowed app can be installed and authenticated before it becomes callable. OpenClaw provisionally admits only ownership-proven, policy-approved apps, creates the thread with _default.enabled = false and explicit app overrides, then calls app/installed once with that thread's ID and forceRefresh: false. If that snapshot reports missing, disabled, or non-callable apps, OpenClaw logs one warning and continues with the remaining tools. Codex still enforces managed restrictions, workspace policy, and app/tool permissions; unavailable apps gain no access.

The check completes before OpenClaw injects history, starts a turn, or persists the native thread binding. If the snapshot request fails, OpenClaw deletes a persistent provisional thread with thread/delete or unsubscribes an ephemeral thread with thread/unsubscribe. If safe cleanup cannot be confirmed, it retires the owning app-server connection. Supervised branches also clean up their temporary probe and retain recovery state when cleanup fails.

With allow_all_plugins, an explicitly disabled configured workspace plugin still denies its owned apps. When app/read does not expose that ownership, OpenClaw uses its plugin/installed snapshot and reads only the exact configured plugin's details to reserve the denied app IDs. It does not scan unrelated marketplaces or install, enable, or authenticate the disabled plugin; missing ownership fails closed.

Only connect OpenClaw to a 0.149.0 or newer remote app-server trusted to accept configured marketplace plugin installs and inventory refreshes. Missing modern inventory methods and server, authentication, or transport failures fail closed.

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.