运行时和 Codex 认证
命名映射¶
| 你看到的名称 | 层 | 含义 |
|---|---|---|
openai |
提供商前缀 | 规范 OpenAI 模型路由;路由事实决定隐式运行时。 |
codex 插件 |
插件 | 捆绑插件,提供原生 Codex app-server 运行时和 /codex 聊天控制。 |
provider/model agentRuntime.id: codex |
代理运行时 | 强制为匹配的嵌入式轮次使用原生 Codex app-server 框架。 |
/codex ... |
聊天命令集 | 从会话中绑定/控制 Codex app-server 线程。 |
runtime: "acp", agentId: "codex" |
ACP 会话路由 | 显式回退路径,通过 ACP/acpx 运行 Codex。 |
隐式代理运行时¶
当 provider/model agentRuntime 策略未设置或为 auto 时,OpenAI 的提供商拥有路由策略会根据有效端点和适配器选择隐式运行时:
| 有效路由事实 | 隐式运行时 |
|---|---|
使用 openai-responses 的精确官方 Platform HTTPS 端点,或使用 openai-chatgpt-responses 的精确官方 ChatGPT HTTPS 端点;无作者编写的提供商请求覆盖 |
可能选择 Codex |
作者编写的 openai-completions 适配器 |
OpenClaw |
| 自定义端点 | OpenClaw |
| 显式使用 HTTP 的精确官方端点 | 被拒绝 |
| 带有作者编写的 provider/model 请求覆盖的路由 | OpenClaw |
有效的模型范围 params.fastMode / params.fast_mode、cutoff 和 thinking 值是类型化的代理运行时控制,而不是作者编写的提供商请求参数。
明确的推理支持和原生推理努力元数据也会保留 Codex 选择。有关支持的能力值以及仍受保护的请求覆盖,请参阅 运行时选择。
加载配置时添加的目录默认值不计为作者编写的请求覆盖。基于文件的 API-key SecretRefs 和机密出口代理也保持与官方 Platform Responses 路由的兼容性;使用该代理时,请保留官方 HTTPS 模型的 baseUrl。
显式 agentRuntime.id: "openclaw" 会将符合 Codex 条件的路由保持在 OpenClaw 上。显式 agentRuntime.id: "codex" 需要已注册的 Codex 框架;不支持的路由/认证会失败关闭,但作者编写的请求覆盖可以在执行前使用 Codex 声明的精确请求 OpenClaw 回退。当配方依赖原生执行时,请检查已完成结果的实际框架。运行时兼容性不会确定凭据类型或计费:Platform API-key 认证和 ChatGPT/Codex 订阅认证仍然不同。
仅官方 Completions 适配器不会将受支持的模型固定到按量计费:旧配置曾将该适配器与 Codex 订阅认证一起使用。当两种凭据类型都符合条件时,自动选择会优先选择订阅路由。该偏好不会改变隐式运行时,也不会要求仅为 API 的配置安装 Codex。没有 auth 覆盖的字面 provider apiKey 在符合条件的配置文件之后仍作为回退。必需的配置文件绑定、provider 认证设置、已配置的机密引用和显式认证顺序仍然优先。作者编写的 OpenClaw 运行时选择在两种类型都符合条件时优先选择 API 路由;运行时兼容性会独立检查。未固定的 heartbeat 和 subagent 模型继承其默认模型的路由意图。Doctor 在保存模型引用迁移后报告已解决的计费路由变更,包括消费者以及旧/新模型、路由和配置文件。
openclaw doctor --fix 将旧版 codex/* 和 openai-codex/* 模型引用、旧版 Codex 认证配置文件 id 以及旧版 Codex 认证顺序条目迁移到规范 openai 路由。迁移后的模型引用会获得模型范围的 agentRuntime.id: "codex";新的认证顺序配置请使用 auth.order.openai。
Note
新的 OpenAI 设置仅在未配置主模型时应用 GPT-5.6 主模型。添加或刷新 OpenAI 认证会保留现有显式选择,包括 openai/gpt-5.5,除非你显式使用 models auth login --set-default 或 models set。仅当你希望为代理模型使用 API-key 认证时,才使用 API-key 认证配置文件。
原生 Codex app-server 认证¶
原生 Codex app-server 框架在符合条件的精确官方 HTTPS 路由隐式选择它,或 provider/model agentRuntime.id: "codex" 显式选择它时,使用 openai/* 模型引用。其认证仍然是基于账户的。OpenClaw 按以下顺序选择认证:
- 代理的有序 OpenAI 认证配置文件,最好位于
auth.order.openai下。运行openclaw doctor --fix以迁移旧版 Codex 认证配置文件 id 和认证顺序。 - 原生 Codex 账户,仅在显式选择
appServer.homeScope: "user"且没有主机凭据或账户选择拥有该路由时。普通 OpenClaw 会话默认使用隔离的代理主目录,即使 Codex 已登录。准备好的 OpenClaw 凭据保留在该主目录中;OpenClaw 永远不会将它们登录到原生用户主目录。 - 仅用于本地 stdio app-server 启动,并且仅在 app-server 报告没有账户时:
CODEX_API_KEY,然后是OPENAI_API_KEY。
启用 user-home 选择加入后,状态和目录读取会询问 Codex 其原生登录情况,而不会将凭据导入 OpenClaw 配置文件。新的身份验证刷新会观察原生登录和登出。原生 API 密钥账户和订阅账户会选择其匹配的路由。模型运行时选择使用与思考元数据相同的路由和账户;不可用的运行时无法被选择。当你希望使用由 OpenClaw 拥有的配置文件时,显式身份验证导入仍然可用。
如果你之前依赖自动使用原生 Codex 登录,请使用 openclaw models auth login --provider openai 登录,并选择生成的 OpenClaw 配置文件。在 Model Setup 中选择检测到的 Codex 会重用符合条件的 OpenClaw 凭据,或在测试连接之前打开受支持的 OpenAI 登录流程。取消或失败的登录不会提升该路由。如果登录后的验证失败,请选择已保存的登录以重试,而无需再次登录。设置不再仅仅因为存在原生登录就启用 user-home 共享。现有的显式 homeScope: "user" 设置仍然是选择加入;删除该设置以使用隔离会话。原生会话采用和监督保持不变。现有的个人 Codex 历史不会被移动或删除,普通 OpenClaw 会话仍持久保存在每个代理的 Codex 主目录中。
默认的每个代理 codex-home/auth.json 不是运行时身份验证存储。如果你在那里复制或挂载了 Codex CLI 凭据,请在开始原生 Codex 回合之前将它们导入该代理的 OpenClaw 身份验证存储。将 <agent-id> 替换为拥有此 Codex 主目录的已配置代理:
openclaw migrate plan codex --from <codex-home> --agent <agent-id> --include-secrets --item auth:openai
openclaw migrate apply codex --from <codex-home> --agent <agent-id> --include-secrets --item auth:openai --yes
本地 ChatGPT/Codex 订阅登录不会仅仅因为网关进程还具有用于直接 OpenAI 模型或嵌入的 OPENAI_API_KEY 而被替换。环境变量 API 密钥回退仅适用于本地 stdio 无账户路径;它永远不会通过 WebSocket 应用服务器连接发送。当选择订阅式 Codex 配置文件时,OpenClaw 还会将 CODEX_API_KEY 和 OPENAI_API_KEY 排除在生成的 stdio 应用服务器子进程之外,并改为通过应用服务器登录 RPC 发送所选凭据。
当该订阅配置文件被 Codex 使用限制阻止时,OpenClaw 会将该配置文件标记为阻止,直到 Codex 公布的重置时间,并让身份验证顺序轮换到下一个 openai:* 配置文件,而不更改所选模型或退出 Codex 框架。重置时间过后,订阅配置文件再次符合条件。
聊天 /status 会报告所选运行时当前已准备账户的身份验证模式。原生登录与 OpenClaw 配置文件保持区分;它不能满足不可用的显式配置文件固定。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw