Documentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
内置 codex 插件让 OpenClaw 通过 Codex app-server 运行嵌入式 OpenAI 智能体轮次，而不是使用内置 PI harness。
当你希望 Codex 拥有底层智能体会话时，请使用 Codex harness：原生线程恢复、原生工具续接、原生压缩以及 app-server 执行。OpenClaw 仍然拥有聊天渠道、会话文件、模型选择、OpenClaw 动态工具、审批、媒体递送，以及可见转录镜像。
常规设置使用规范 OpenAI 模型引用，例如 openai/gpt-5.5。不要配置 openai-codex/gpt-* 模型引用。将 OpenAI 智能体认证顺序放在 auth.order.openai 下；较旧的 openai-codex:* 配置文件和 auth.order.openai-codex 条目仍支持现有安装。
OpenClaw 使用 Codex 原生代码模式并启用仅代码模式来启动 Codex app-server 线程。这样会将延迟执行/可搜索的 OpenClaw 动态工具保留在 Codex 自身的代码执行和工具搜索界面内，而不是在 Codex 之上添加 PI 风格的工具搜索包装器。
关于更广泛的模型/提供商/运行时拆分，请从 Agent Runtimes 开始。简短版本是：openai/gpt-5.5 是模型引用，codex 是运行时，而 Telegram、Discord、Slack 或其他渠道仍然是通信界面。
- OpenClaw 中有可用的内置
codex 插件。
- 如果你的配置使用
plugins.allow，请包含 codex。
- Codex app-server
0.125.0 或更新版本。内置插件默认管理兼容的 Codex app-server 二进制文件，因此 PATH 上的本地 codex 命令不会影响常规 harness 启动。
- Codex 认证可通过
openclaw models auth login --provider openai-codex、智能体的 Codex home 中的 app-server 账户，或显式的 Codex API 密钥认证配置文件提供。
有关认证优先级、环境隔离、自定义 app-server 命令、模型发现以及所有配置字段，请参阅 Codex harness reference。
快速开始
大多数想在 OpenClaw 中使用 Codex 的用户需要这条路径：使用 ChatGPT/Codex 订阅登录，启用内置 codex 插件，并使用规范的 openai/gpt-* 模型引用。
使用 Codex OAuth 登录：
openclaw models auth login --provider openai-codex
codex 插件并选择一个 OpenAI 智能体模型：
{
plugins: {
entries: {
codex: {
enabled: true,
},
},
},
agents: {
defaults: {
model: "openai/gpt-5.5",
},
},
}
plugins.allow，也请在那里添加 codex：
{
plugins: {
allow: ["codex"],
entries: {
codex: {
enabled: true,
},
},
},
}
/new 或 /reset，这样下一轮会从当前配置解析 harness。
快速开始配置是最小可用的 Codex harness 配置。在 OpenClaw 配置中设置 Codex harness 选项，并且仅将 CLI 用于 Codex 认证：
| 需求 | 设置 | 位置 |
|---|
| 启用 harness | plugins.entries.codex.enabled: true | OpenClaw 配置 |
| 保留允许列表插件安装 | 在 plugins.allow 中包含 codex | OpenClaw 配置 |
| 通过 Codex 路由 OpenAI 智能体轮次 | agents.defaults.model 或 agents.list[].model 设为 openai/gpt-* | OpenClaw 智能体配置 |
| 使用 Codex OAuth 登录 | openclaw models auth login --provider openai-codex | CLI 认证配置文件 |
| 为 Codex 运行添加 API 密钥备用 | 在 auth.order.openai 中订阅认证之后列出 openai:* API 密钥配置文件 | 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-* 模型引用。优先使用 auth.order.openai 来表达订阅优先/API 密钥备用的顺序。现有 openai-codex:* 认证配置文件和 auth.order.openai-codex 仍然有效，但不要编写新的 openai-codex/gpt-* 模型引用。
{
auth: {
order: {
openai: ["openai-codex:user@example.com", "openai:api-key-backup"],
},
},
}
openai/gpt-* 智能体轮次，两个配置文件仍然都会通过 Codex 运行。API 密钥只是认证回退，而不是切换到 PI 或普通 OpenAI Responses 的请求。
本页其余部分覆盖用户必须在其中选择的常见变体：部署形态、关闭失败路由、guardian 审批策略、原生 Codex 插件以及 Computer Use。有关完整选项列表、默认值、枚举、发现、环境隔离、超时和 app-server 传输字段，请参阅 Codex harness reference。
验证 Codex 运行时
在你预期使用 Codex 的聊天中使用 /status。由 Codex 支持的 OpenAI 智能体轮次会显示：
然后检查 Codex app-server 状态：
/codex status
/codex models
/codex status 会报告 app-server 连接性、账户、速率限制、MCP 服务器和 Skills。/codex models 会列出该 harness 和账户的实时 Codex app-server 目录。如果 /status 的结果出乎意料，请参阅 故障排除。
路由和模型选择
将提供商引用和运行时策略分开：
- 对于通过 Codex 的 OpenAI 智能体轮次，使用
openai/gpt-*。
- 不要在配置中使用
openai-codex/gpt-*。运行 openclaw doctor --fix 来修复旧版引用和过期的会话路由固定项。
agentRuntime.id: "codex" 对于常规 OpenAI 自动模式是可选的，但当部署应在 Codex 不可用时关闭失败时很有用。- 当你有意这样做时，
agentRuntime.id: "pi" 会让提供商或模型进入直接 PI 行为。
/codex ... 从聊天中控制原生 Codex app-server 对话。- ACP/acpx 是单独的外部 harness 路径。仅当用户要求 ACP/acpx 或外部 harness 适配器时才使用它。
常见命令路由：
| 用户意图 | 使用 |
|---|
| 附加当前聊天 | /codex bind [--cwd <path>] |
| 恢复现有 Codex 线程 | /codex resume <thread-id> |
| 列出或筛选 Codex 线程 | /codex threads [filter] |
| 仅发送 Codex 反馈 | /codex diagnostics [note] |
| 启动 ACP/acpx 任务 | ACP/acpx 会话命令，而不是 /codex |
| 用例 | 配置 | 验证 | 备注 |
|---|
| 使用原生 Codex 运行时的 ChatGPT/Codex 订阅 | openai/gpt-* 加上启用的 codex 插件 | /status 显示 Runtime: OpenAI Codex | 推荐路径 |
| Codex 不可用时关闭失败 | 提供商或模型 agentRuntime.id: "codex" | 轮次失败，而不是回退到 PI | 用于仅 Codex 部署 |
| 通过 PI 的直接 OpenAI API 密钥流量 | 提供商或模型 agentRuntime.id: "pi" 和常规 OpenAI 认证 | /status 显示 PI 运行时 | 仅在有意使用 PI 时使用 |
| 旧版配置 | openai-codex/gpt-* | openclaw doctor --fix 会重写它 | 不要以这种方式编写新配置 |
| ACP/acpx Codex 适配器 | ACP sessions_spawn({ runtime: "acp" }) | ACP 任务/会话状态 | 与原生 Codex harness 分离 |
agents.defaults.imageModel 遵循相同的前缀拆分。正常 OpenAI 路由使用 openai/gpt-*，只有当图像理解应该通过有界 Codex app-server 轮次运行时才使用 codex/gpt-*。不要使用 openai-codex/gpt-*；doctor 会将该旧版前缀重写为 openai/gpt-*。
部署模式
基础 Codex 部署
当所有 OpenAI 智能体轮次默认都应使用 Codex 时，请使用快速开始配置。
{
plugins: {
entries: {
codex: {
enabled: true,
},
},
},
agents: {
defaults: {
model: "openai/gpt-5.5",
},
},
}
混合提供商部署
这种形态将 Claude 保留为默认智能体，并添加一个命名 Codex 智能体：
{
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 智能体使用其常规提供商路径，而 codex 智能体使用 Codex app-server。
关闭失败的 Codex 部署
对于 OpenAI 智能体轮次，当内置插件可用时，openai/gpt-* 已经会解析到 Codex。当你想要一条明文的关闭失败规则时，请添加显式运行时策略：
{
models: {
providers: {
openai: {
agentRuntime: {
id: "codex",
},
},
},
},
agents: {
defaults: {
model: "openai/gpt-5.5",
},
},
plugins: {
entries: {
codex: {
enabled: true,
},
},
},
}
App-server 策略
默认情况下，该插件会通过 stdio 传输在本地启动 OpenClaw 管理的 Codex 二进制文件。仅当你有意运行不同的可执行文件时，才设置 appServer.command。仅当 app-server 已在其他位置运行时，才使用 WebSocket 传输：
{
plugins: {
entries: {
codex: {
enabled: true,
config: {
appServer: {
transport: "websocket",
url: "ws://gateway-host:39175",
authToken: "${CODEX_APP_SERVER_TOKEN}",
},
},
},
},
},
}
approvalPolicy: "never"、approvalsReviewer: "user" 和
sandbox: "danger-full-access"。如果本地 Codex 要求不允许这种
隐式 YOLO 姿态，OpenClaw 会改为选择允许的 guardian 权限。
当会话启用了 OpenClaw 沙箱时，OpenClaw 会将 Codex
danger-full-access 收窄为 Codex workspace-write，让原生 Codex 代码模式轮次
保持在沙箱隔离的工作区内。
当你希望 Codex 在沙箱逃逸或额外权限之前执行原生自动审核时，请使用 guardian 模式：
{
plugins: {
entries: {
codex: {
enabled: true,
config: {
appServer: {
mode: "guardian",
serviceTier: "priority",
},
},
},
},
},
}
approvalPolicy: "on-request"、approvalsReviewer: "auto_review" 和
sandbox: "workspace-write"。
有关每个 app-server 字段、身份验证顺序、环境隔离、发现和
超时行为，请参阅 Codex harness reference。
命令和诊断
内置插件会在任何支持 OpenClaw 文本命令的渠道上注册 /codex 作为斜杠命令。
常见形式：
/codex status 检查 app-server 连接、模型、账户、速率限制、
MCP 服务器和 Skills。/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 Skills。
对于大多数支持报告，请在发生错误的对话中从 /diagnostics [note] 开始。
它会创建一份 Gateway 网关诊断报告，并且对于 Codex harness 会话，会请求批准以发送相关的 Codex 反馈包。
有关隐私模型和群聊行为，请参阅 诊断导出。
仅当你明确想为当前附加的线程上传 Codex 反馈，而不发送完整的 Gateway 网关
诊断包时，才使用 /codex diagnostics [note]。
本地检查 Codex 线程
检查异常 Codex 运行最快的方法通常是直接打开原生 Codex 线程：
从已完成的 /diagnostics 回复、/codex binding 或
/codex threads [filter] 获取线程 ID。
有关上传机制和运行时级诊断边界，请参阅
Codex harness runtime。
身份验证按以下顺序选择：
- 该智能体的有序 OpenAI 身份验证配置文件，最好位于
auth.order.openai 下。现有 openai-codex:* 配置文件 ID 仍然有效。
- 该智能体的 Codex home 中 app-server 的现有账户。
- 仅对于本地 stdio app-server 启动，在没有 app-server 账户且仍需要 OpenAI 身份验证时，使用
CODEX_API_KEY，然后使用
OPENAI_API_KEY。
当 OpenClaw 发现 ChatGPT 订阅样式的 Codex 身份验证配置文件时，它会从生成的 Codex 子进程中移除
CODEX_API_KEY 和 OPENAI_API_KEY。这会让 Gateway 网关级 API key 仍可用于嵌入或直接 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 运行时。
如果部署需要额外的环境隔离，请将这些变量添加到
appServer.clearEnv：
{
plugins: {
entries: {
codex: {
enabled: true,
config: {
appServer: {
clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],
},
},
},
},
},
}
appServer.clearEnv 只影响生成的 Codex app-server 子进程。
Codex 动态工具默认使用 searchable 加载。OpenClaw 不会暴露
与 Codex 原生工作区操作重复的动态工具：read、write、
edit、apply_patch、exec、process 和 update_plan。其余 OpenClaw
集成工具，例如消息、会话、媒体、cron、浏览器、节点、
gateway、heartbeat_respond 和 web_search，可通过 openclaw 命名空间下的 Codex 工具
搜索使用，从而缩小初始模型上下文。
sessions_yield 和仅消息工具的来源回复保持直接可用，因为这些是轮次控制契约。Heartbeat 协作说明会告诉 Codex：
当工具尚未加载时，在结束 Heartbeat 轮次前搜索 heartbeat_respond。
仅在连接到无法搜索延迟动态工具的自定义 Codex
app-server，或调试完整工具载荷时，才设置 codexDynamicToolsLoading: "direct"。
支持的顶层 Codex 插件字段：
| 字段 | 默认值 | 含义 |
|---|
codexDynamicToolsLoading | "searchable" | 使用 "direct" 将 OpenClaw 动态工具直接放入初始 Codex 工具上下文。 |
codexDynamicToolsExclude | [] | 要从 Codex app-server 轮次中省略的其他 OpenClaw 动态工具名称。 |
codexPlugins | disabled | 为已迁移的源安装精选插件提供原生 Codex 插件/app 支持。 |
appServer 字段：
| 字段 | 默认值 | 含义 |
|---|
transport | "stdio" | "stdio" 会生成 Codex；"websocket" 会连接到 url。 |
command | managed Codex binary | stdio 传输的可执行文件。保持未设置以使用托管二进制文件；仅在需要显式覆盖时设置。 |
args | ["app-server", "--listen", "stdio://"] | stdio 传输的参数。 |
url | unset | WebSocket app-server URL。 |
authToken | unset | WebSocket 传输的 Bearer 令牌。 |
headers | {} | 额外 WebSocket 标头。 |
clearEnv | [] | OpenClaw 构建继承环境后，从生成的 stdio app-server 进程中移除的额外环境变量名称。CODEX_HOME 和 HOME 保留用于 OpenClaw 在本地启动时按智能体隔离 Codex。 |
requestTimeoutMs | 60000 | app-server 控制平面调用的超时时间。 |
turnCompletionIdleTimeoutMs | 60000 | 在轮次作用域的 Codex app-server 请求之后，OpenClaw 等待 turn/completed 时的静默窗口。对于较慢的工具后或仅状态综合阶段，请提高此值。 |
mode | "yolo" unless local Codex requirements disallow YOLO | YOLO 或 guardian 审核执行的预设。若本地 stdio 要求省略 danger-full-access、never 审批或 user 审核者，则隐式默认值会变为 guardian。 |
approvalPolicy | "never" or an allowed guardian approval policy | 发送到线程启动/恢复/轮次的原生 Codex 审批策略。guardian 默认值在允许时优先使用 "on-request"。 |
sandbox | "danger-full-access" or an allowed guardian sandbox | 发送到线程启动/恢复的原生 Codex 沙箱模式。guardian 默认值在允许时优先使用 "workspace-write"，否则使用 "read-only"。当 OpenClaw 沙箱处于活动状态时，danger-full-access 会收窄为 "workspace-write"。 |
approvalsReviewer | "user" or an allowed guardian reviewer | 使用 "auto_review" 可在允许时让 Codex 审核原生审批提示，否则使用 guardian_subagent 或 user。guardian_subagent 仍是旧版别名。 |
serviceTier | unset | 可选 Codex app-server 服务层级。"priority" 启用快速模式路由，"flex" 请求 flex 处理，null 清除覆盖值，旧版 "fast" 会被接受为 "priority"。 |
appServer.requestTimeoutMs 进行限制：Codex item/tool/call 请求默认使用 30 秒的 OpenClaw 看门狗。正数的每次调用 timeoutMs 参数会延长或缩短该特定工具预算。image_generate 工具在工具调用未提供自身超时时，也会使用 agents.defaults.imageGenerationModel.timeoutMs；媒体理解 image 工具则使用 tools.media.image.timeoutSeconds 或其 60 秒媒体默认值。动态工具预算上限为 600000 ms。超时时，OpenClaw 会在支持的位置中止工具信号，并向 Codex 返回失败的动态工具响应，以便轮次可以继续，而不是让会话停留在 processing。
OpenClaw 响应 Codex 轮次范围内的 app-server 请求后，harness 还期望 Codex 通过 turn/completed 完成原生轮次。如果 app-server 在该响应之后经过 appServer.turnCompletionIdleTimeoutMs 仍保持静默，OpenClaw 会尽力中断 Codex 轮次，记录诊断超时，并释放 OpenClaw 会话通道，使后续聊天消息不会排在过期的原生轮次之后。同一轮次的任何非终止通知（包括 rawResponseItem/completed）都会解除这个短看门狗，因为 Codex 已证明该轮次仍处于活动状态；较长的终止看门狗会继续保护真正卡住的轮次。全局 app-server 通知（例如速率限制更新）不会重置轮次空闲进度。当 Codex 发出已完成的 agentMessage 条目，然后在没有 turn/completed 的情况下保持静默时，OpenClaw 会将助手输出视为实际上已完成，尽力中断原生 Codex 轮次，并释放会话通道。超时诊断包括最后一个 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
当 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。对于可重复部署，配置是首选方式，因为它会将插件行为保留在与其余 Codex harness 设置相同的已审查文件中。
Native Codex plugins
Native Codex plugins 支持会在与 OpenClaw harness 轮次相同的 Codex 线程中使用 Codex app-server 自身的应用和插件能力。OpenClaw 不会将 Codex 插件转换为合成的 codex_plugin_* OpenClaw 动态工具。
codexPlugins 只影响选择原生 Codex harness 的会话。它对 PI 运行、普通 OpenAI provider 运行、ACP 对话绑定或其他 harness 没有影响。
最小迁移配置：
{
plugins: {
entries: {
codex: {
enabled: true,
config: {
codexPlugins: {
enabled: true,
allow_destructive_actions: true,
plugins: {
"google-calendar": {
enabled: true,
marketplaceName: "openai-curated",
pluginName: "google-calendar",
},
},
},
},
},
},
},
}
codexPlugins 后，请使用 /new、/reset 或重启 Gateway 网关，以便未来的 Codex harness 会话使用更新后的应用集启动。
关于迁移资格、应用清单、破坏性操作策略、引导式请求和原生插件诊断，请参阅 Native Codex plugins。
Computer Use
Computer Use 在其自己的设置指南中介绍：
Codex Computer Use。
简短说明：OpenClaw 不会内置桌面控制应用，也不会自行执行桌面操作。它会准备 Codex app-server，验证 computer-use MCP 服务器可用，然后在 Codex 模式轮次期间让 Codex 拥有原生 MCP 工具调用。
运行时边界
Codex harness 只更改低层嵌入式智能体执行器。
- 支持 OpenClaw 动态工具。Codex 要求 OpenClaw 执行这些工具，因此 OpenClaw 仍处于执行路径中。
- Codex 原生 shell、patch、MCP 和原生应用工具由 Codex 拥有。OpenClaw 可以通过受支持的中继观察或阻止选定的原生事件，但不会重写原生工具参数。
- Codex 拥有原生压缩。OpenClaw 会保留转录镜像，用于频道历史、搜索、
/new、/reset，以及未来的模型或 harness 切换。
- 媒体生成、媒体理解、TTS、审批和消息工具输出继续通过匹配的 OpenClaw 提供商/模型设置进行。
tool_result_persist 适用于 OpenClaw 拥有的转录工具结果，而不是 Codex 原生工具结果记录。
关于钩子层、受支持的 V1 表面、原生权限处理、队列 Steering、Codex 反馈上传机制和压缩详情，请参阅 Codex harness runtime。
故障排除
Codex 未显示为普通 /model 提供商： 对于新配置，这是预期行为。选择一个 openai/gpt-* 模型，启用 plugins.entries.codex.enabled，并检查 plugins.allow 是否排除了 codex。
OpenClaw 使用 PI 而不是 Codex： 确保模型引用是官方 OpenAI provider 上的 openai/gpt-*，并且 Codex 插件已安装且启用。如果你在测试时需要严格证明，请设置提供商或模型 agentRuntime.id: "codex"。强制 Codex 运行时会失败，而不是回退到 PI。
仍存在旧版 openai-codex/* 配置： 运行 openclaw doctor --fix。Doctor 会将旧版模型引用重写为 openai/*，移除过期的会话和整个智能体运行时固定项，并保留现有的 auth-profile 覆盖。
app-server 被拒绝： 使用 Codex app-server 0.125.0 或更新版本。同版本预发布或带构建后缀的版本（例如 0.125.0-alpha.2 或 0.125.0+custom）会被拒绝，因为 OpenClaw 测试的是稳定版 0.125.0 协议下限。
/codex status 无法连接： 检查内置 codex 插件是否已启用，在配置了 allowlist 时检查 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： 除非提供商或模型运行时策略将其路由到另一个 harness，否则这是预期行为。普通非 OpenAI 提供商引用在 auto 模式下会继续使用其正常提供商路径。
Computer Use 已安装但工具不运行： 在新会话中检查 /codex computer-use status。如果工具报告 Native hook relay unavailable，请使用 /new 或 /reset；如果问题持续存在，请重启 Gateway 网关以清除过期的原生钩子注册。请参阅 Codex Computer Use。
