Codex plugin config fields

Supported plugins.entries.codex.config fields and their defaults. Part of the Codex harness guide; Where each section moved lists every section.

Config fields

Supported top-level Codex plugin fields:

Field	Default	Meaning
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.
sessionCatalog	enabled	Sidebar discovery for native Codex sessions on this Gateway and eligible paired nodes.
supervision	disabled	Agent-facing native-session transcript and write-control policy.

Supported appServer fields:

Field	Default	Meaning
transport	"stdio"	"stdio" spawns Codex; explicit "unix" connects to the local control socket; "websocket" connects to url.
homeScope	"agent"	"agent" isolates ordinary harness state per OpenClaw agent. "user" is an explicit opt-in that shares the native $CODEX_HOME or ~/.codex, uses native auth, and enables owner-only thread management. User scope supports local stdio or Unix transport. For the separate supervision connection, an unset value resolves to "user" for stdio or Unix and "agent" for WebSocket.
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 or unix:// URL. An empty explicit Unix path selects the canonical user-home control socket.
authToken	unset	Bearer token for WebSocket transport. Accepts a literal string or SecretInput such as ${CODEX_APP_SERVER_TOKEN}.
headers	{}	Extra WebSocket headers. Header values accept literal strings or SecretInput values, for example x-codex-client-session-token: "${CODEX_CLIENT_SESSION_TOKEN}".
clearEnv	[]	Extra environment variable names removed from the spawned stdio app-server process after OpenClaw builds its inherited environment. OpenClaw keeps the selected CODEX_HOME and inherited HOME for local launches.
codeModeOnly	false	Opt into Codex’s code-mode-only tool surface. Ordinary OpenClaw dynamic tools remain available through nested tools.* calls; openclaw_direct tools stay directly model-visible.
remoteWorkspaceRoot	unset	Remote Codex app-server workspace root. OpenClaw maps the local cwd into this root and transfers authoritative remote attachments over an output-capped, no-shell command/exec reader. Paths escaping either workspace, symbolic links, oversized files, and unbounded attachment batches fail closed; uploads retain the configured channel identity and app-server request timeout.
requestTimeoutMs	60000	Timeout for app-server control-plane calls.
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.
approvalPolicy	"never" or an allowed guardian approval policy	Native Codex approval policy sent to thread start/resume/turn. Guardian defaults prefer "on-request" when allowed.
sandbox	"danger-full-access" or an allowed guardian sandbox	Native Codex sandbox mode sent to thread start/resume. Guardian defaults prefer "workspace-write" when allowed, otherwise "read-only". When an OpenClaw sandbox is active, danger-full-access turns use Codex workspace-write with network access derived from the OpenClaw sandbox egress setting.
approvalsReviewer	"user" or an allowed guardian reviewer	Use "auto_review" to let Codex review native approval prompts when allowed, otherwise guardian_subagent or user. guardian_subagent remains a legacy alias.
serviceTier	unset	Native Codex app-server preference only. Any non-empty string passes through for forward compatibility; documented values are "priority" and "flex". null clears the override, and legacy "fast" normalizes to "priority". This is neither the shared Fast-mode setting nor a direct embedded OpenAI setting. A shared Fast run control supersedes it with priority or null, or decides per model call in auto mode.
cyberFailover	automatic Daybreak Blue escalation	Controls the automatic retry after an OpenAI cyber-policy refusal. mode ("auto" default, or "off") enables it, model (default "gpt-daybreak-blue-latest") is the escalation target, and cooloffMs (default 600000) bounds the session window that follows an attempt. Escalation retries a refused turn once, never changes the stored model selection, and treats an unauthorized target as unavailable rather than retrying it. See Runtime behavior.
networkProxy	disabled	Opt into Codex permissions-profile networking for app-server commands. OpenClaw defines the selected permissions.<profile>.network config and selects it with default_permissions instead of sending sandbox.
experimental.sandboxExecServer	false	Preview opt-in that registers an OpenClaw sandbox-backed Codex environment with the supported Codex app-server so native Codex execution can run inside the active OpenClaw sandbox.

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. By default, OpenClaw generates a collision-resistant openclaw-network-<fingerprint> profile name from the profile body; use profileName only when a stable local name is required.

{
  plugins: {
    entries: {
      codex: {
        config: {
          appServer: {
            approvalPolicy: "never",
            sandbox: "workspace-write",
            networkProxy: {
              enabled: true,
              domains: {
                "api.openai.com": "allow",
                "blocked.example.com": "deny",
              },
              unixSockets: {
                "/tmp/proxy.sock": "allow",
                "/tmp/blocked.sock": "none",
              },
              allowUpstreamProxy: true,
              proxyUrl: "http://127.0.0.1:3128",
            },
          },
        },
      },
    },
  },
}

With enabled: true, domains uses Codex’s native host matching. Hosts absent from the effective native allowlist are denied unless the configured approval policy permits an explicit exception. Set approvalPolicy: "never", as above, to prevent approval-based exceptions. Native system requirements can contribute allowed domains or select a managed allowlist, so this map does not replace the system’s network policy. Explicit denies in the effective policy take precedence over overlapping allows and cannot be approved.

Use *.example.com for subdomains or **.example.com for both the apex domain and subdomains. These restrictions apply to commands run through the Codex sandbox. They do not restrict Gateway traffic, model-provider requests, or unrelated MCP processes.

With networkProxy.enabled: true, invalid configuration fails with the rejected field path, without logging configuration values. After a plugin update, saved configuration with blank optional networkProxy.profileName or remoteWorkspaceRoot values needs an explicit openclaw doctor --fix before Codex can run. Doctor removes those blank values while keeping the domain policy. Fix other invalid fields manually before retrying. Valid configurations need no repair.

If the normal app-server runtime would be danger-full-access, enabling networkProxy uses workspace-style filesystem access for the generated permission profile: Codex managed network enforcement is sandboxed networking, so a full-access profile would not protect outbound traffic. Domain entries use allow or deny. Unix socket entries use allow or none; OpenClaw translates none to Codex’s native deny permission.