古法编程

Appearance

Codex 插件参考文档，涵盖所有配置字段、传输方式（stdio / WebSocket）、认证顺序、审批和沙箱模式、模型发现、超时设置以及动态工具加载规则。默认使用托管 Codex 二进制文件的 stdio 传输，YOLO 模式允许无审批运行；开启 guardian 模式后可启用审批和沙箱。模型发现默认开启，超时 2500ms，失败后使用内置回退模型列表。动态工具默认以 searchable 方式加载，避免初始上下文过大。

Codex 插件配置参考 ​

本文档是 OpenClaw 中 codex 插件的详细配置参考。完整的设置和路由决策请先阅读 Codex 插件。

插件配置表面 ​

所有 Codex 插件设置位于 plugins.entries.codex.config 下。

json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 2500,
          },
          appServer: {
            mode: "guardian",
          },
        },
      },
    },
  },
}

支持的顶级字段：

字段默认值说明
discoveryenabledCodex app-server 的模型发现设置（model/list）。
appServermanaged stdio app-server传输方式、命令、认证、审批、沙箱和超时设置。
codexDynamicToolsLoading"searchable"设为 "direct" 可将 OpenClaw 动态工具直接放入初始 Codex 工具上下文中。
codexDynamicToolsExclude[]额外排除的 OpenClaw 动态工具名称，不会传递给 Codex app-server。
codexPluginsdisabled原生 Codex 插件/应用支持（针对已迁移的源码安装插件），参见 Codex 原生插件。
computerUsedisabledCodex Computer Use 设置，参见 Codex Computer Use。

App-server 传输方式 ​

默认情况下，OpenClaw 启动绑定的托管 Codex 二进制文件：

bash
codex app-server --listen stdio://

这样 app-server 版本与绑定的 codex 插件保持一致，而不是本地安装的任意 Codex CLI。只有当你想故意运行不同可执行文件时，才设置 appServer.command。

对于已在运行中的 app-server，使用 WebSocket 传输：

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

支持的 appServer 字段：

字段默认值说明
transport"stdio""stdio" 会启动 Codex 子进程；"websocket" 连接到 url。
commandmanaged Codex binarystdio 传输使用的可执行文件。不设置则使用托管二进制文件。
args["app-server", "--listen", "stdio://"]stdio 传输的命令行参数。
url未设置WebSocket app-server URL。
authToken未设置WebSocket 传输的 Bearer token。
headers{}额外的 WebSocket 请求头。
clearEnv[]OpenClaw 构建继承环境后，从启动的 stdio app-server 子进程中移除的额外环境变量名称。
requestTimeoutMs60000app-server 控制面调用的超时时间（毫秒）。
turnCompletionIdleTimeoutMs60000Codex 接受一个 turn 后，或在一个 turn 内的 app-server 请求后，等待 turn/completed 的静默时间窗口（毫秒）。
postToolRawAssistantCompletionIdleTimeoutMs未设置（默认使用 assistant completion idle timeout）工具切换后，Codex 发出原始 assistant completion 或 progress 但未发送 turn/completed 时的 completion-idle 保护。用于预期后处理较长的可靠或重负载场景。
mode"yolo"（除非本地 Codex 要求不允许 YOLO）预设为 YOLO 或 guardian 审核模式。
approvalPolicy"never" 或 guardian 允许的审批策略原生 Codex 审批策略，传递给 thread start、resume 和 turn。
sandbox"danger-full-access" 或 guardian 允许的沙箱模式原生 Codex 沙箱模式，传递给 thread start 和 resume。如果启用了 OpenClaw 沙箱，danger-full-access 的 turn 被降级为 workspace-write；turn 的网络标志跟随 OpenClaw 沙箱的 egress 设置。
approvalsReviewer"user" 或 guardian 允许的审核者设为 "auto_review" 可在允许时让 Codex 自行审核原生审批提示。
defaultWorkspaceDir当前进程目录--cwd 未设置时 /codex bind 使用的工作目录。
serviceTier未设置可选的 Codex app-server 服务层级。"priority" 启用快速模式路由，"flex" 请求灵活处理，null 清除覆盖。旧版 "fast" 视为 "priority"。
experimental.sandboxExecServerfalse预览功能：注册一个 OpenClaw 沙箱驱动的 Codex 环境，要求 Codex app-server 0.132.0 或更新版本，使原生 Codex 执行运行在 OpenClaw 沙箱内。

插件会阻止较旧或未版本的 app-server 握手。Codex app-server 必须报告稳定版本 0.125.0 或更新。

审批和沙箱模式 ​

本地 stdio app-server 会话默认使用 YOLO 模式：approvalPolicy: "never"，approvalsReviewer: "user"，sandbox: "danger-full-access"。这种受信任的本地操作者姿态允许无人值守的 OpenClaw turns 和 heartbeat 前进，而无需回答无人响应的审批提示。

如果 Codex 的本地系统需求文件不允许隐式 YOLO 审批、审核者或沙箱值，OpenClaw 会改用 guardian 模式并选择 guardian 允许的权限。同一需求文件中匹配主机名的 [[remote_sandbox_config]] 条目会影响沙箱默认值的决策。

设置 appServer.mode: "guardian" 启用 Codex guardian 审核审批：

json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            serviceTier: "priority",
          },
        },
      },
    },
  },
}

guardian 预设展开为：approvalPolicy: "on-request"，approvalsReviewer: "auto_review"，sandbox: "workspace-write"（当这些值被允许时）。单个策略字段可以覆盖 mode。旧的 guardian_subagent 审核者值仍被接受为兼容别名，但新配置应使用 auto_review。

当 OpenClaw 沙箱激活时，本地 Codex app-server 进程仍在 Gateway 主机上运行。因此 OpenClaw 会禁用该 turn 的 Codex 原生 Code Mode、用户 MCP 服务器和 app 支持的插件执行，而不是将 Codex 主机端沙箱视为 OpenClaw 沙箱后端的等价物。Shell 访问通过 OpenClaw 沙箱驱动的动态工具（如 sandbox_exec 和 sandbox_process）暴露，前提是正常的 exec/process 工具可用。

在 Ubuntu/AppArmor 主机上，当你在没有激活 OpenClaw 沙箱的情况下有意运行原生 Codex workspace-write 时，bwrap 可能在 shell 命令启动前失败。如果看到 bwrap: setting up uid map: Permission denied 或 bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted，运行 openclaw doctor 并修复 OpenClaw 服务用户的报告的主机组命名空间策略，而不是授予更宽泛的 Docker 容器权限。建议为服务进程使用限定的 AppArmor 配置文件；kernel.apparmor_restrict_unprivileged_userns=0 回退方案影响整个主机，存在安全权衡。

沙箱化的原生执行 ​

稳定默认值是 fail-closed：激活的 OpenClaw 沙箱会禁用本应在 Codex app-server 主机上运行的原生 Codex 执行功能。仅当你希望尝试使用 OpenClaw 沙箱后端的 Codex 远程环境支持时，才设置 appServer.experimental.sandboxExecServer: true。此预览路径需要 Codex app-server 0.132.0 或更新版本。

json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            experimental: {
              sandboxExecServer: true,
            },
          },
        },
      },
    },
  },
}

当该标志启用且当前 OpenClaw 会话处于沙箱化状态时，OpenClaw 会启动一个由活动沙箱支持的本地回环 exec-server，将其注册到 Codex app-server，然后通过该 OpenClaw 拥有的环境启动 Codex thread 和 turn。如果 app-server 无法注册该环境，运行会失败（fail-closed），而不是静默回退到主机执行。

此预览路径仅限于本地。远程 WebSocket app-server 无法到达本地回环 exec-server（除非在同一主机上运行），因此 OpenClaw 会拒绝这种组合。

认证和环境隔离 ​

认证按以下顺序选择：

  1. 该智能体的显式 OpenClaw Codex 认证配置。
  2. 该智能体 Codex home 中 app-server 的现有账户。
  3. 仅限本地 stdio app-server 启动：当没有 app-server 账户且仍需要 OpenAI 认证时，使用 CODEX_API_KEY，然后是 OPENAI_API_KEY。

当 OpenClaw 检测到 ChatGPT 订阅风格的 Codex 认证配置时，它会从启动的 Codex 子进程中移除 CODEX_API_KEY 和 OPENAI_API_KEY。这样可以为 embeddings 或直接 OpenAI 模型保留 Gateway 级别的 API 密钥，同时避免原生 Codex app-server turns 意外通过 API 产生费用。

显式 Codex API-key 配置和本地 stdio env-key 回退使用 app-server login，而不是继承子进程环境。WebSocket app-server 连接不接收 Gateway env API-key 回退；请使用显式认证配置或远程 app-server 自己的账户。

Stdio app-server 启动默认继承 OpenClaw 的进程环境。OpenClaw 管理 Codex app-server 账户桥接，并将 CODEX_HOME 设置为该智能体 OpenClaw 状态下的每个智能体目录。这样 Codex 配置、账户、插件缓存/数据和线程状态都限定在该 OpenClaw 智能体范围内，而不是从操作员个人的 ~/.codex home 泄漏。

OpenClaw 不会为正常的本地 app-server 启动重写 HOME。Codex 运行的子进程（如 openclaw、gh、git、云 CLI 和 shell 命令）会看到正常的进程 home，可以访问用户 home 配置和令牌。Codex 也可能发现 $HOME/.agents/skills 和 $HOME/.agents/plugins/marketplace.json；这种 .agents 发现是有意与操作员 home 共享的，与隔离的 ~/.codex 状态分开。

OpenClaw 插件和 OpenClaw 技能快照仍然通过 OpenClaw 自己的插件注册表和技能加载器流动。个人 Codex ~/.codex 资产则不会。如果你有应成为 OpenClaw 智能体一部分的有用 Codex CLI 技能或插件，请显式迁移它们：

bash
openclaw migrate codex --dry-run
openclaw migrate apply codex --yes

如果部署需要额外的环境隔离，将变量添加到 appServer.clearEnv：

json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],
          },
        },
      },
    },
  },
}

appServer.clearEnv 仅影响启动的 Codex app-server 子进程。OpenClaw 在本地启动标准化期间会从该列表中移除 CODEX_HOME 和 HOME：CODEX_HOME 保留为每个智能体，HOME 保持继承以便子进程使用正常的用户 home 状态。

动态工具 ​

Codex 动态工具默认以 searchable 方式加载。OpenClaw 不会暴露与 Codex 原生工作区操作重复的动态工具：

  • read
  • write
  • edit
  • apply_patch
  • exec
  • process
  • update_plan

其余大多数 OpenClaw 集成工具（如 messaging、media、cron、browser、nodes、gateway、heartbeat_respond、web_search）可通过 Codex 工具搜索在 openclaw 命名空间下使用。这使初始模型上下文保持较小。sessions_yield 和仅消息工具的源回复保持直接暴露，因为它们是 turn 控制合约。sessions_spawn 保持可搜索状态，这样 Codex 的原生 spawn_agent 仍是主要的 Codex 子智能体界面，同时通过 openclaw 动态工具命名空间仍然可以进行显式 OpenClaw 或 ACP 委派。

仅当你连接到无法搜索延迟动态工具的自定义 Codex app-server 或调试完整工具有效负载时，才设置 codexDynamicToolsLoading: "direct"。

超时 ​

OpenClaw 拥有的动态工具调用与 appServer.requestTimeoutMs 相互独立。每个 Codex item/tool/call 请求按以下顺序使用第一个可用的超时：

  • 正数的 per-call timeoutMs 参数。
  • 对于 image_generate：agents.defaults.imageGenerationModel.timeoutMs。
  • 对于未配置超时的 image_generate：120 秒的图像生成默认值。
  • 对于媒体理解工具 image：tools.media.image.timeoutSeconds 转换为毫秒，或 60 秒的媒体默认值。
  • 30 秒的动态工具默认值。

动态工具预算上限为 600000 毫秒。超时时，OpenClaw 会在支持的情况下中止工具信号，并向 Codex 返回失败的动态工具响应，以便 turn 可以继续而非让会话停留在 processing 状态。

在 Codex 接受一个 turn 后，以及在 OpenClaw 响应一个 turn 范围的 app-server 请求后，harness 期望 Codex 在当前 turn 中取得进展并最终通过 turn/completed 完成原生 turn。如果 app-server 在 appServer.turnCompletionIdleTimeoutMs 内保持静默，OpenClaw 会尽力中断 Codex turn，记录诊断超时，并释放 OpenClaw 会话通道，以免后续聊天消息排队在陈旧的原生 turn 之后。

大多数非终结通知（通知同一 turn）会解除该短看门狗，因为 Codex 已证明 turn 仍然活跃。原始 custom_tool_call_output 完成会保持短后工具看门狗武装，因为它们是 turn 范围的工具结果交接。完成的 agentMessage 项和预工具原始 assistant rawResponseItem/completed 项会武装 assistant 输出释放：如果 Codex 随后保持静默而不发送 turn/completed，OpenClaw 会尽力中断原生 turn 并释放会话通道。后工具原始 assistant 进度会继续等待 turn/completed，同时一个 completion-idle 保护保持武装；该保护使用 appServer.postToolRawAssistantCompletionIdleTimeoutMs（如果已配置），否则回退到 assistant completion idle timeout。超时诊断包括最后一个 app-server 通知方法，对于原始 assistant 响应项还包括项类型、角色、id 以及有限长度（有界）的 assistant 文本预览。

模型发现 ​

默认情况下，Codex 插件向 app-server 询问可用模型。模型可用性由 Codex app-server 拥有，因此当 OpenClaw 升级绑定的 @openai/codex 版本或部署指向不同 Codex 二进制文件的 appServer.command 时，列表可能会变化。可用性也可能与账户相关。在运行中的 Gateway 上使用 /codex models 查看该 harness 和账户的实时目录。

如果发现失败或超时，OpenClaw 会使用内置回退目录，包含：

  • GPT-5.5
  • GPT-5.4 mini
  • GPT-5.2

当前捆绑的 harness 是 @openai/codex 0.132.0。针对该捆绑 app-server 的 model/list 探测返回：

模型 ID默认隐藏输入模态推理努力
gpt-5.5是否text, imagelow, medium, high, xhigh
gpt-5.4否否text, imagelow, medium, high, xhigh
gpt-5.4-mini否否text, imagelow, medium, high, xhigh
gpt-5.3-codex否否text, imagelow, medium, high, xhigh
gpt-5.2否否text, imagelow, medium, high, xhigh
codex-auto-review否是text, imagelow, medium, high, xhigh

隐藏模型可以由 app-server 目录返回用于内部或专门流程，但它们不是正常的模型选择器选项。

在 plugins.entries.codex.config.discovery 下调整发现参数：

json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 2500,
          },
        },
      },
    },
  },
}

当你希望启动时避免探测 Codex 并仅使用回退目录时，禁用发现：

json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: false,
          },
        },
      },
    },
  },
}

工作区启动文件 ​

Codex 通过原生项目文档发现自行处理 AGENTS.md。OpenClaw 不会写入合成的 Codex 项目文档文件，也不依赖 Codex 后备文件名作为角色文件，因为 Codex 后备文件仅在 AGENTS.md 缺失时生效。

为保持 OpenClaw 工作区一致性，Codex harness 解析其他启动文件。SOUL.md、IDENTITY.md、TOOLS.md 和 USER.md 会作为 OpenClaw Codex 开发者指令转发，因为它们定义了活动智能体、可用工作区指导和用户配置。HEARTBEAT.md 内容不会被注入；heartbeat turns 会获得一个协作模式指针来读取该文件（当文件存在且非空时）。BOOTSTRAP.md 和 MEMORY.md（如果存在）会作为 OpenClaw turn 输入引用上下文转发。

环境覆盖 ​

环境覆盖仍可用于本地测试：

  • 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

当 appServer.command 未设置时，OPENCLAW_CODEX_APP_SERVER_BIN 绕过托管二进制文件。

OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 已移除。请改用 plugins.entries.codex.config.appServer.mode: "guardian"，或使用 OPENCLAW_CODEX_APP_SERVER_MODE=guardian 进行一次性本地测试。对于可重复部署，配置（config）更优，因为它将插件行为放在与 Codex harness 其他设置相同的审核文件中。

相关文档 ​

常见问题 ​

启动 Codex 插件后，模型列表为空或发现超时怎么办？ ​

检查 plugins.entries.codex.config.discovery 中的 enabled 和 timeoutMs（默认 2500ms）。如果超时，OpenClaw 会使用内置回退模型列表（GPT-5.5、GPT-5.4 mini、GPT-5.2）。确保 Codex app-server 版本 ≥0.125.0 并可访问。可以暂时禁用发现（enabled: false）使用回退目录测试。运行中的 Gateway 上使用 /codex models 命令查看实时模型目录。

怎么从 YOLO 模式切换到 guardian 模式并启用审批？ ​

设置 plugins.entries.codex.config.appServer.mode: "guardian"。这会自动将审批策略设为 on-request、审核者设为 auto_review、沙箱设为 workspace-write（如果允许）。你也可以单独覆盖字段，比如 approvalPolicy: "always"、approvalsReviewer: "user"。如果遇到 bwrap 权限错误，运行 openclaw doctor 并修复服务用户的命名空间策略。

WebSocket 连接 Codex app-server 时，认证失败或超时怎么办？ ​

WebSocket 传输需要 authToken（Bearer token）和正确的 url。OpenClaw 不会为 WebSocket 连接注入 Gateway 环境中的 API 密钥回退。请在插件配置中直接设置 authToken（例如 ${CODEX_APP_SERVER_TOKEN}），或确保远程 app-server 已登录。检查 requestTimeoutMs 是否足够（默认 60000ms），必要时增大。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策