Appearance
OpenClaw 的 codex 插件可让 OpenAI agent 的对话通过 Codex app-server 执行，替代内置的 PI 运行时。你需要启用插件、使用 openai/gpt-* 模型引用，并通过 openclaw models auth login --provider openai-codex 登录。如果不想在 Codex 不可用时回退到 PI，可显式设置 agentRuntime.id: "codex"；若需直接使用 OpenAI API，则设置 agentRuntime.id: "pi"。检查运行时是否生效：在聊天中运行 /status，看到 Runtime: OpenAI Codex 即为成功。
OpenClaw Codex Harness 配置与故障排查
内置的 codex 插件允许 OpenClaw 通过 Codex app-server 运行嵌入的 OpenAI agent 对话，而不是使用内置的 PI 运行时。
当你希望 Codex 管理底层 agent 会话（原生线程恢复、原生工具延续、原生压缩和 app-server 执行）时，使用 Codex harness。OpenClaw 仍然负责聊天渠道、会话文件、模型选择、OpenClaw 动态工具、审批、媒体传递以及对可见 transcript 的镜像。
正常配置使用规范的 OpenAI 模型引用，例如 openai/gpt-5.5。不要配置 openai-codex/gpt-* 模型引用。将 OpenAI agent 认证顺序放在 auth.order.openai 下；现有的 openai-codex:* 配置文件和 auth.order.openai-codex 条目仍然受支持。
当没有 OpenClaw 沙箱激活时，OpenClaw 会以 Codex 原生代码模式启动 Codex app-server 线程，但代码模式独占默认为关闭。这使 Codex 原生的 workspace 和代码能力可用，同时 OpenClaw 动态工具继续通过 app-server 的 item/tool/call 桥工作。激活的 OpenClaw 沙箱和受限工具策略会完全禁用原生代码模式，除非你选择加入实验性的沙箱 exec-server 路径。
关于更广泛的模型/提供者/运行时分离，请从 Agent runtimes 开始。简而言之：openai/gpt-5.5 是模型引用，codex 是运行时，Telegram、Discord、Slack 或其他渠道作为通信面。
前提条件
- OpenClaw 必须包含可用的内置
codex插件。 - 如果你的配置使用了
plugins.allow，请确保包含codex。 - Codex app-server 版本需为
0.125.0或更新。默认情况下内置插件管理兼容的 Codex app-server 二进制文件，因此本地的codex命令不会影响正常的启动流程。 - Codex 认证可通过以下方式之一提供：
openclaw models auth login --provider openai-codex登录- agent 的 Codex home 目录中已有 app-server 账号
- 显式的 Codex API-key 认证配置文件
关于认证优先级、环境隔离、自定义 app-server 命令、模型发现和所有配置字段，请参阅 Codex harness reference。
快速开始
大多数想在 OpenClaw 中使用 Codex 的用户按以下路径操作：使用 ChatGPT/Codex 订阅登录、启用内置 codex 插件、使用规范的 openai/gpt-* 模型引用。
用 Codex OAuth 登录：
bash
openclaw models auth login --provider openai-codex启用内置 codex 插件并选择 OpenAI agent 模型：
json5
{
plugins: {
entries: {
codex: {
enabled: true,
},
},
},
agents: {
defaults: {
model: "openai/gpt-5.5",
},
},
}如果你的配置使用了 plugins.allow，也把 codex 加进去：
json5
{
plugins: {
allow: ["codex"],
entries: {
codex: {
enabled: true,
},
},
},
}修改插件配置后重启网关。如果已有聊天存在会话，在测试运行时变更前使用 /new 或 /reset 命令，以便下一轮对话从当前配置解析运行时。
配置
快速开始配置是最小可行的 Codex harness 配置。在 OpenClaw 配置中设置 Codex harness 选项，仅使用 CLI 进行 Codex 认证：
| 需要 | 配置 | 位置 |
|---|---|---|
| 启用插件 | plugins.entries.codex.enabled: true | OpenClaw 配置 |
| 保持白名单插件安装 | 在 plugins.allow 中包含 codex | OpenClaw 配置 |
| 将 OpenAI agent 对话路由到 Codex | agents.defaults.model 或 agents.list[].model 设为 openai/gpt-* | OpenClaw agent 配置 |
| 使用 Codex OAuth 登录 | openclaw models auth login --provider openai-codex | CLI 认证配置文件 |
| 为 Codex 运行添加 API-key 备份 | 将 openai:* API-key 配置文件放在 auth.order.openai 中订阅认证之后 | CLI 认证配置文件 + OpenClaw 配置 |
| Codex 不可用时拒绝服务 | 提供者或模型中设置 agentRuntime.id: "codex" | OpenClaw 模型/提供者配置 |
| 使用直接的 OpenAI API 流量 | 提供者或模型中设置 agentRuntime.id: "pi" 及正常 OpenAI 认证 | OpenClaw 模型/提供者配置 |
| 调整 app-server 行为 | plugins.entries.codex.config.appServer.* | Codex 插件配置 |
| 启用原生 Codex 插件应用 | plugins.entries.codex.config.codexPlugins.* | Codex 插件配置 |
| 启用 Codex Computer Use | plugins.entries.codex.config.computerUse.* | Codex 插件配置 |
使用 openai/gpt-* 模型引用用于 Codex 支持的 OpenAI agent 对话。优先使用 auth.order.openai 的订阅优先 / API-key 备份顺序。现有的 openai-codex:* 认证配置文件和 auth.order.openai-codex 仍然有效，但不要写新的 openai-codex/gpt-* 模型引用。
不要在 Codex 支持的 agent 上设置 compaction.model 或 compaction.provider，除非选中的上下文引擎拥有压缩。没有拥有压缩的上下文引擎时，Codex 通过其原生 app-server 线程状态进行压缩，OpenClaw 会在运行时忽略这些本地摘要覆盖项，并且 openclaw doctor --fix 会在 agent 使用 Codex 时移除它们。
Lossless 作为上下文引擎仍然受支持。通过 plugins.slots.contextEngine: "lossless-claw" 和 plugins.entries.lossless-claw.config.summaryModel 配置，而不是 agents.defaults.compaction.provider。当 Codex 是活动运行时，openclaw doctor --fix 会将旧的 compaction.provider: "lossless-claw" 格式迁移到 Lossless 上下文引擎槽。
当活动上下文引擎报告 ownsCompaction: true 时，/compact 会运行该引擎的压缩生命周期，并使绑定的 Codex app-server 线程失效。下一个 Codex 对话会启动一个新的后端线程，并从上下文引擎中重新填充，而不是在引擎拥有的语义摘要之上叠加 Codex 原生压缩。
json5
{
auth: {
order: {
openai: ["openai-codex:user@example.com", "openai:api-key-backup"],
},
},
}在这个结构中，两个配置文件仍通过 Codex 运行 openai/gpt-* agent 对话。API 密钥仅作为认证回退，不是切换到 PI 或普通 OpenAI Responses 的请求。
本页剩余部分介绍用户必须在常见变体之间做选择的部分：部署形态、失败关闭路由、guardian 审批策略、原生 Codex 插件和 Computer Use。关于所有选项列表、默认值、枚举、发现、环境隔离、超时和 app-server 传输字段，请参阅 Codex harness reference。
验证 Codex 运行时
在期望 Codex 出现的聊天中使用 /status 命令。Codex 支持的 OpenAI agent 对话会显示：
text
Runtime: OpenAI Codex然后检查 Codex app-server 状态：
text
/codex status
/codex models/codex status 报告 app-server 连接性、账号、速率限制、MCP 服务器和技能。/codex models 列出针对该插件和账号的实时 Codex app-server 目录。如果 /status 结果出人意料，请参阅故障排查。
路由与模型选择
将提供者引用和运行时策略分开：
- 使用
openai/gpt-*让 OpenAI agent 对话通过 Codex 运行。 - 不要在配置中使用
openai-codex/gpt-*。运行openclaw doctor --fix修复遗留引用和过时的会话路由固定。 agentRuntime.id: "codex"在普通的 OpenAI 自动模式下是可选的，但当部署需要 Codex 不可用时拒绝服务时很有用。agentRuntime.id: "pi"可以让提供者或模型在被有意选择时走直接的 PI 行为。/codex ...控制从聊天发起的原生 Codex app-server 对话。- ACP/acpx 是一个独立的外部插件路径。仅当用户明确要求 ACP/acpx 或外部插件适配器时使用。
常见命令路由：
| 用户意图 | 使用 |
|---|---|
| 将当前聊天绑定到 Codex 线程 | /codex bind [--cwd <path>] |
| 恢复已有的 Codex 线程 | /codex resume <thread-id> |
| 列出或过滤 Codex 线程 | /codex threads [filter] |
| 列出原生 Codex 插件 | /codex plugins list |
| 启用或禁用一个配置好的原生 Codex 插件 | /codex plugins enable <name>、/codex plugins disable <name> |
| 在配对的节点上附加一个已有的 Codex CLI 会话 | /codex sessions --host <node> [filter]，然后 /codex resume <session-id> --host <node> --bind here |
| 仅发送 Codex 反馈 | /codex diagnostics [note] |
| 启动一个 ACP/acpx 任务 | ACP/acpx 会话命令，不是 /codex |
| 使用场景 | 配置 | 验证 | 说明 |
|---|---|---|---|
| ChatGPT/Codex 订阅 + 原生 Codex 运行时 | openai/gpt-* 加上启用的 codex 插件 | /status 显示 Runtime: OpenAI Codex | 推荐路径 |
| Codex 不可用时拒绝服务 | 提供者或模型 agentRuntime.id: "codex" | 对话失败而不是回退到 PI | 用于 Codex 专属部署 |
| 通过 PI 的直接 OpenAI API-key 流量 | 提供者或模型 agentRuntime.id: "pi" 和正常 OpenAI 认证 | /status 显示 PI 运行时 | 仅在有意使用 PI 时选择 |
| 遗留配置 | openai-codex/gpt-* | openclaw doctor --fix 重写 | 不要写新配置 |
| ACP/acpx Codex 适配器 | ACP sessions_spawn({ runtime: "acp" }) | ACP 任务/会话状态 | 独立于原生 Codex 插件 |
agents.defaults.imageModel 使用相同前缀。使用 openai/gpt-* 走正常 OpenAI 路径，仅在图像理解应该通过有界的 Codex app-server 对话运行时使用 codex/gpt-*。不要使用 openai-codex/gpt-*；doctor 会将此遗留前缀重写为 openai/gpt-*。
部署模式
基本 Codex 部署
当所有 OpenAI agent 对话默认应使用 Codex 时，使用快速开始配置。
json5
{
plugins: {
entries: {
codex: {
enabled: true,
},
},
},
agents: {
defaults: {
model: "openai/gpt-5.5",
},
},
}混合提供者部署
此结构保持 Claude 作为默认 agent，并添加一个命名 Codex agent：
json5
{
plugins: {
entries: {
codex: {
enabled: true,
},
},
},
agents: {
defaults: {
model: "anthropic/claude-opus-4-6",
},
list: [
{
id: "main",
default: true,
model: "anthropic/claude-opus-4-6",
},
{
id: "codex",
name: "Codex",
model: "openai/gpt-5.5",
},
],
},
}使用此配置，main agent 使用其正常的提供者路径，codex agent 使用 Codex app-server。
失败关闭的 Codex 部署
对于 OpenAI agent 对话，openai/gpt-* 已解析到 Codex（当内置插件可用时）。当你想要明确的失败关闭规则时，添加显式运行时策略：
json5
{
models: {
providers: {
openai: {
agentRuntime: {
id: "codex",
},
},
},
},
agents: {
defaults: {
model: "openai/gpt-5.5",
},
},
plugins: {
entries: {
codex: {
enabled: true,
},
},
},
}当强制 Codex 时，OpenClaw 会在 Codex 插件被禁用、app-server 过旧或无法启动时提前失败。
App-server 策略
默认情况下，插件启动 OpenClaw 管理的 Codex 二进制文件，使用 stdio 传输。仅在你有意运行不同可执行文件时设置 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}",
},
},
},
},
},
}本地 stdio app-server 会话默认采用信任本地操作员姿态：approvalPolicy: "never"、approvalsReviewer: "user"、sandbox: "danger-full-access"。如果本地 Codex 要求不允许这种隐含的 YOLO 姿态，OpenClaw 会改用允许的 guardian 权限。当 OpenClaw 沙箱为会话激活时，OpenClaw 会禁用 Codex 原生代码模式、用户 MCP 服务器和基于应用的插件执行，而不是依赖 Codex 主机的沙箱。Shell 访问通过 OpenClaw 沙箱支持的动态工具（如 sandbox_exec 和 sandbox_process）暴露，当正常的 exec/process 工具可用时。
使用 guardian 模式时，要求 Codex 原生自动审查：
json5
{
plugins: {
entries: {
codex: {
enabled: true,
config: {
appServer: {
mode: "guardian",
serviceTier: "priority",
},
},
},
},
},
}Guardian 模式会扩展到 Codex app-server 审批，通常为 approvalPolicy: "on-request"、approvalsReviewer: "auto_review"、sandbox: "workspace-write"（当本地要求允许这些值时）。
关于每个 app-server 字段、认证顺序、环境隔离、发现和超时行为，请参阅 Codex harness reference。
命令和诊断
内置插件会在任何支持 OpenClaw 文本命令的渠道上注册 /codex 斜杠命令。
常见形式：
/codex status检查 app-server 连接性、模型、账号、速率限制、MCP 服务器和技能。/codex models列出实时 Codex app-server 模型。/codex threads [filter]列出最近的 Codex app-server 线程。/codex resume <thread-id>将当前 OpenClaw 会话附加到已有的 Codex 线程。/codex compact要求 Codex app-server 压缩附加线程。/codex review启动 Codex 原生审查。/codex diagnostics [note]发送前询问是否发送 Codex 反馈。/codex account显示账号和速率限制状态。/codex mcp列出 Codex app-server MCP 服务器状态。/codex skills列出 Codex app-server 技能。
对于大多数支持报告，在出现 bug 的对话中使用 /diagnostics [note]。这会创建一个 Gateway 诊断报告，并且对于 Codex 插件会话，会请求批准发送相关的 Codex 反馈包。详见 Diagnostics export。
当你只想为当前附加线程上传 Codex 反馈，而不需要完整的 Gateway 诊断包时，使用 /codex diagnostics [note]。
本地检查 Codex 线程
检查有问题的 Codex 运行最快的方式通常是直接打开原生 Codex 线程：
bash
codex resume <thread-id>从完成的 /diagnostics 回复、/codex binding 或 /codex threads [filter] 获取线程 ID。
关于上传机制和运行时级诊断边界，请参阅 Codex harness runtime。
认证按以下顺序选择：
- 为 agent 排序的 OpenAI 认证配置文件，最好在
auth.order.openai下。现有openai-codex:*配置文件 ID 仍然有效。 - app-server 在该 agent 的 Codex home 中已有的账号。
- 仅针对本地 stdio app-server 启动：
CODEX_API_KEY，然后是OPENAI_API_KEY（当没有 app-server 账号且 OpenAI 认证仍然需要时）。
当 OpenClaw 看到 ChatGPT 订阅风格的 Codex 认证配置文件时，它会从启动的 Codex 子进程中移除 CODEX_API_KEY 和 OPENAI_API_KEY。这样 Gateway 级别的 API 密钥仍可用于嵌入或直接 OpenAI 模型，而不让原生 Codex app-server 对话意外通过 API 计费。显式的 Codex API-key 配置文件和本地 stdio 环境变量回退使用 app-server 登录，而不是继承子进程环境变量。WebSocket app-server 连接不会收到 Gateway 环境 API-key 回退；请使用显式认证配置文件或远程 app-server 自己的账号。
如果订阅配置文件达到 Codex 使用限制，OpenClaw 会记录 Codex 报告的恢复时间，并尝试下一个有序的认证配置文件来执行相同的 Codex 运行。当恢复时间过去后，订阅配置文件再次可用，无需更改所选的 openai/gpt-* 模型或 Codex 运行时。
对于本地 stdio app-server 启动，OpenClaw 将 CODEX_HOME 设置为每个 agent 的目录，因此 Codex 配置、认证/账号文件、插件缓存/数据和原生线程状态不会读取或写入操作员的个人 ~/.codex。OpenClaw 保留正常的进程 HOME；Codex 运行的子进程仍然可以找到用户主目录的配置和令牌，Codex 也可能发现共享的 $HOME/.agents/skills 和 $HOME/.agents/plugins/marketplace.json 条目。
如果部署需要额外的环境隔离，将这些变量添加到 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 保持按 agent 隔离，HOME 保持继承以便子进程可以使用正常的用户主目录状态。
Codex 动态工具默认以 searchable 方式加载。OpenClaw 不会暴露与 Codex 原生 workspace 操作重复的动态工具：read、write、edit、apply_patch、exec、process、update_plan。大多数剩余的 OpenClaw 集成工具（如消息、媒体、cron、浏览器、节点、网关、heartbeat_respond、web_search）可通过 Codex 工具搜索在 openclaw 命名空间下使用，从而保持初始模型上下文更小。sessions_yield 和仅消息工具的源回复保持直接，因为它们是对话控制契约。sessions_spawn 保持可搜索，以便 Codex 的原生 spawn_agent 仍然是主要的 Codex 子 agent 表面，而显式的 OpenClaw 或 ACP 委托仍可通过 openclaw 动态工具命名空间使用。Heartbeat 协作指令告诉 Codex 在结束心跳对话之前搜索 heartbeat_respond（当该工具尚未加载时）。
仅当连接到无法搜索延迟动态工具的自定义 Codex app-server 时，或调试完整工具负载时，设置 codexDynamicToolsLoading: "direct"。
受支持的顶层 Codex 插件字段：
| 字段 | 默认值 | 含义 |
|---|---|---|
codexDynamicToolsLoading | "searchable" | 使用 "direct" 将 OpenClaw 动态工具直接放入初始 Codex 工具上下文中。 |
codexDynamicToolsExclude | [] | 从 Codex app-server 对话中排除的额外 OpenClaw 动态工具名称。 |
codexPlugins | 禁用 | 对迁移的源安装精选插件的原生 Codex 插件/应用支持。 |
受支持的 appServer 字段：
| 字段 | 默认值 | 含义 |
|---|---|---|
transport | "stdio" | "stdio" 启动 Codex；"websocket" 连接到 url。 |
command | 管理的 Codex 二进制文件 | stdio 传输的可执行文件。保持未设置以使用管理的二进制文件；仅当需要显式覆盖时设置。 |
args | ["app-server", "--listen", "stdio://"] | stdio 传输的参数。 |
url | 未设置 | WebSocket app-server URL。 |
authToken | 未设置 | WebSocket 传输的 Bearer token。 |
headers | {} | 额外的 WebSocket 头。 |
clearEnv | [] | 从启动的 stdio app-server 进程中移除的额外环境变量名称（OpenClaw 构建其继承环境后）。OpenClaw 会保留按 agent 的 CODEX_HOME 和继承的 HOME（对于本地启动）。 |
codeModeOnly | false | 选择加入 Codex 的代码模式专用工具表面。OpenClaw 动态工具仍然在 Codex 中注册，因此嵌套的 tools.* 调用会通过 app-server 的 item/tool/call 桥返回。 |
requestTimeoutMs | 60000 | app-server 控制面调用的超时。 |
turnCompletionIdleTimeoutMs | 60000 | Codex 接受一轮或一轮范围内的 app-server 请求后，OpenClaw 等待 turn/completed 的静默窗口。对于较慢的后工具或仅状态合成阶段，增加此值。 |
postToolRawAssistantCompletionIdleTimeoutMs | 未设置 | 工具传递后 Codex 发出原始助手完成或进度但未发送 turn/completed 时使用的完成空闲守卫。默认情况下使用助手完成空闲超时。将此用于信任或繁重工作负载，其中后工具合成可以合法地保持静默时间超过最终助手发布预算。 |
mode | "yolo"（除非本地 Codex 要求不允许 YOLO） | YOLO 或 guardian 审查执行的预设。省略 danger-full-access、never 审批或 user 审查者的本地 stdio 要求会使隐含默认值变为 guardian。 |
approvalPolicy | "never" 或允许的 guardian 审批策略 | 发送到线程开始/恢复/对话的原生 Codex 审批策略。Guardian 默认优先选择 "on-request"（当允许时）。 |
sandbox | "danger-full-access" 或允许的 guardian 沙箱模式 | 发送到线程开始/恢复的原生 Codex 沙箱模式。Guardian 默认优先选择 "workspace-write"（当允许时），否则为 "read-only"。当 OpenClaw 沙箱激活时，danger-full-access 回合会使用 Codex workspace-write，网络访问来自 OpenClaw 沙箱的 egress 设置。 |
approvalsReviewer | "user" 或允许的 guardian 审查者 | 使用 "auto_review" 让 Codex 在允许时审查原生审批提示，否则为 guardian_subagent 或 user。guardian_subagent 是遗留别名。 |
serviceTier | 未设置 | 可选的 Codex app-server 服务层。"priority" 启用快速模式路由，"flex" 请求 flex 处理，null 清除覆盖，遗留 "fast" 被接受为 "priority"。 |
experimental.sandboxExecServer | false | 预览选项，注册一个 OpenClaw 沙箱支持的 Codex 环境（需要 Codex app-server 0.132.0 或更新），使原生 Codex 执行可以在活动 OpenClaw 沙箱内运行。 |
OpenClaw 拥有的动态工具调用独立于 appServer.requestTimeoutMs 进行限界：Codex item/tool/call 请求默认使用 30 秒的 OpenClaw 看门狗。每个调用正值的 timeoutMs 参数会延长或缩短该特定工具的预算。当工具调用没有提供自己的超时时，image_generate 工具使用 agents.defaults.imageGenerationModel.timeoutMs，否则使用 120 秒的图片生成默认值。媒体理解的 image 工具使用 tools.media.image.timeoutSeconds 或其 60 秒的媒体默认值。动态工具预算上限为 600000 ms。超时后，OpenClaw 会中止工具信号（如果支持），并向 Codex 返回失败的动态工具响应，以便对话可以继续而不是将会话留在 processing 状态。
Codex 接受一轮对话后，以及 OpenClaw 响应一轮范围内的 app-server 请求后，插件期望 Codex 在当前轮内取得进展并最终以 turn/completed 结束原生轮。如果 app-server 静默超过 appServer.turnCompletionIdleTimeoutMs，OpenClaw 会尽最大努力中断 Codex 轮，记录诊断超时，并释放 OpenClaw 会话通道，以便后续聊天消息不会被陈旧的本地轮阻塞。大多数同一轮的终端通知会重置该短看门狗，因为 Codex 已证明该轮仍然存活；原始的 custom_tool_call_output 完成会保持短的轮后看门狗处于布防状态，因为它们是轮范围内的工具结果移交。全局 app-server 通知（如速率限制更新）不会重置轮空闲进度。完成的 agentMessage 项和预工具原始助手 rawResponseItem/completed 项会布防助手输出释放：如果 Codex 随后静默而未收到 turn/completed，OpenClaw 会尽最大努力中断本地轮并释放会话通道。轮后原始助手进度会继续等待 turn/completed，同时一个完成空闲守卫保持布防；该守卫使用 appServer.postToolRawAssistantCompletionIdleTimeoutMs（如果配置），否则回退到助手完成空闲超时。超时诊断包括最后一个 app-server 通知方法，对于原始助手响应项，包括项类型、角色、ID 和有限制的助手文本预览。
环境覆盖仍可用于本地测试：
OPENCLAW_CODEX_APP_SERVER_BINOPENCLAW_CODEX_APP_SERVER_ARGSOPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardianOPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICYOPENCLAW_CODEX_APP_SERVER_SANDBOX
OPENCLAW_CODEX_APP_SERVER_BIN 在 appServer.command 未设置时绕过管理的二进制文件。
OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 已被移除。请改用 plugins.entries.codex.config.appServer.mode: "guardian"，或在一次性测试中使用 OPENCLAW_CODEX_APP_SERVER_MODE=guardian。对于可重复的部署，配置更优，因为它将插件行为与其余 Codex 插件设置放在同一个审核的文件中。
原生 Codex 插件
原生 Codex 插件支持使用 Codex app-server 自己的应用和插件能力，在同一个 Codex 线程中运行 OpenClaw 插件对话。OpenClaw 不会将 Codex 插件翻译成合成的 codex_plugin_* OpenClaw 动态工具。
codexPlugins 仅影响选择了原生 Codex 插件的会话。它对 PI 运行、正常的 OpenAI 提供者运行、ACP 对话绑定或其他插件没有影响。
最小迁移配置：
json5
{
plugins: {
entries: {
codex: {
enabled: true,
config: {
codexPlugins: {
enabled: true,
allow_destructive_actions: true,
plugins: {
"google-calendar": {
enabled: true,
marketplaceName: "openai-curated",
pluginName: "google-calendar",
},
},
},
},
},
},
},
}线程应用配置在 OpenClaw 建立 Codex 插件会话或替换陈旧的 Codex 线程绑定时计算。它不是每轮都重新计算的。更改 codexPlugins 后，使用 /new、/reset 或重启网关，以便将来的 Codex 插件会话使用更新的应用集启动。
关于迁移资格、应用目录、破坏性操作策略、引子以及原生插件诊断，请参阅 Native Codex plugins。
Computer Use
Computer Use 在其自己的设置指南中介绍：Codex Computer Use。
简而言之：OpenClaw 不提供桌面控制应用，也不自行执行桌面操作。它会准备 Codex app-server，验证 computer-use MCP 服务器是否可用，然后让 Codex 在 Codex 模式对话期间拥有原生 MCP 工具调用。
运行时边界
Codex 插件仅更改底层的嵌入式 agent 执行器。
- OpenClaw 动态工具受支持。Codex 要求 OpenClaw 执行这些工具，因此 OpenClaw 仍在执行路径中。
- Codex 原生的 shell、patch、MCP 和原生应用工具由 Codex 拥有。OpenClaw 可以通过支持的中继观察或阻止选定的原生事件，但不重写原生工具参数。
- Codex 拥有原生压缩，除非活动的 OpenClaw 上下文引擎声明
ownsCompaction: true。OpenClaw 维护一个 transcript 镜像，用于渠道历史、搜索、/new、/reset和未来的模型或插件切换。 - 媒体生成、媒体理解、TTS、审批和消息工具输出继续通过匹配的 OpenClaw 提供者/模型设置。
tool_result_persist适用于 OpenClaw 拥有的 transcript 工具结果，而不是 Codex 原生的工具结果记录。
关于钩子层、受支持的 V1 表面、原生权限处理、队列引导、Codex 反馈上传机制和压缩详情，请参阅 Codex harness runtime。
故障排查
Codex 没有作为正常的 /model 提供者出现： 对于新配置这很正常。选择一个 openai/gpt-* 模型，启用 plugins.entries.codex.enabled，并检查 plugins.allow 是否排除了 codex。
OpenClaw 使用了 PI 而不是 Codex： 确保模型引用是 openai/gpt-* 来自官方 OpenAI 提供者，并且 Codex 插件已安装并启用。如果你在测试时需要严格验证，可以设置提供者或模型 agentRuntime.id: "codex"。强制使用 Codex 时，运行失败而不是回退到 PI。
OpenAI Codex 运行时回退到 API-key 路径： 收集一个脱敏的 gateway 摘录，显示模型、运行时、选中的提供者和失败信息。要求受影响的协作者在其 OpenClaw 主机上运行此只读命令：
bash
(
pattern='openai/gpt-5\.[45]|agentRuntime(\.id)?|harnessRuntime|Runtime: OpenAI Codex|openai-codex|resolveSelectedOpenAIPiRuntimeProvider|candidateProvider[": ]+openai|status[": ]+401|Incorrect API key|No API key|api-key path|API-key path|OAuth'
if ls /tmp/openclaw/openclaw-*.log >/dev/null 2>&1; then
grep -E -i -n "$pattern" /tmp/openclaw/openclaw-*.log 2>/dev/null || true
else
journalctl --user -u openclaw-gateway --since today --no-pager 2>/dev/null \
| grep -E -i "$pattern" || true
fi
) | sed -E \
-e 's/(Authorization: Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \
-e 's/(Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \
-e 's/(api[_ -]?key[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \
-e 's/(OPENAI_API_KEY[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \
-e 's/sk-[A-Za-z0-9_-]{12,}/sk-[REDACTED]/g' \
-e 's/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/[EMAIL-REDACTED]/g' \
| tail -200有用的摘录通常包含 openai/gpt-5.5 或 openai/gpt-5.4、Runtime: OpenAI Codex、agentRuntime.id 或 harnessRuntime、candidateProvider: "openai"，以及 401、Incorrect API key 或 No API key 结果。正确的运行应显示 openai-codex OAuth 路径，而不是普通 OpenAI API-key 失败。
遗留的 openai-codex/* 配置仍然存在： 运行 openclaw doctor --fix。Doctor 将遗留模型引用重写为 openai/*，移除过时的会话和整个 agent 运行时固定，并保留现有的认证配置文件覆盖。
app-server 被拒绝： 使用 Codex app-server 0.125.0 或更新。相同版本的预发布或构建后缀版本（如 0.125.0-alpha.2 或 0.125.0+custom）会被拒绝，因为 OpenClaw 测试的是稳定的 0.125.0 协议基础。
/codex status 无法连接： 检查内置的 codex 插件是否已启用，当配置了白名单时 plugins.allow 是否包含它，以及任何自定义的 appServer.command、url、authToken 或 headers 是否有效。
模型发现慢： 降低 plugins.entries.codex.config.discovery.timeoutMs 或禁用发现。请参阅 Codex harness reference。
WebSocket 传输立即失败： 检查 appServer.url、authToken、headers，以及远程 app-server 是否使用相同的 Codex app-server 协议版本。
非 Codex 模型使用了 PI： 这是预期的，除非提供者或模型运行时策略将其路由到另一个插件。普通的非 OpenAI 提供者引用在 auto 模式下保持其正常的提供者路径。
Computer Use 已安装但工具不运行： 从新会话检查 /codex computer-use status。如果某个工具报告 Native hook relay unavailable，使用 /new 或 /reset；如果持续存在，重启网关以清除过时的原生钩子注册。请参阅 Codex Computer Use。
常见问题
怎么确认 OpenClaw 当前使用了 Codex 而不是 PI？
在聊天中运行 /status 命令。如果显示 Runtime: OpenAI Codex，则说明 Codex 正在使用。如果显示 PI 或其它值，请检查模型引用是否为 openai/gpt-* 并且 codex 插件已启用。你也可以临时设置 agentRuntime.id: "codex" 来强制使用 Codex，若失败则直接报错，不回退到 PI。
Codex 对话经常回退到 API-key 路径怎么办？
这通常意味着 OpenAI 认证配置文件中订阅认证失败或顺序不对。运行 openclaw doctor --fix 修复遗留配置，并确保 auth.order.openai 中首先列出 openai-codex:user@example.com 这种订阅配置文件，其次才是 API-key 备份。检查日志中是否出现 401、Incorrect API key 或 No API key 等关键词。
运行 /codex status 提示无法连接怎么解决？
首先确认 codex 插件已在配置中启用（plugins.entries.codex.enabled: true），并且 plugins.allow 若存在则包含 codex。然后检查使用的 Codex app-server 版本是否不低于 0.125.0。若使用自定义 appServer.command、url 或 authToken，确保这些值有效。对于 WebSocket 传输，还需验证远程 app-server 的协议版本与本地匹配。