运行时和 Codex 认证

命名映射¶

隐式代理运行时¶

当提供商/模型 agentRuntime 策略未设置或为 auto 时，OpenAI 的提供商所有路由策略会根据有效端点和适配器选择隐式运行时：

有效的模型作用域 params.fastMode / params.fast_mode、cutoff 和 thinking 值是类型化的代理运行时控制项，而不是编写的提供商请求参数。 肯定的推理支持和原生推理力度元数据也会保留 Codex 选择。有关支持的能力值以及仍然受保护的请求覆盖，请参阅 运行时选择。

显式 agentRuntime.id: "openclaw" 会将符合 Codex 条件的路由保持在 OpenClaw 上。显式 agentRuntime.id: "codex" 需要已注册的 Codex 框架； 不支持的路由/身份验证会失败关闭，但编写的请求覆盖可以在执行前使用 Codex 声明的精确请求 OpenClaw 回退。当配方依赖原生执行时，检查已完成结果的实际框架。 运行时兼容性不会确定凭据类型或计费：Platform API 密钥身份验证和 ChatGPT/Codex 订阅身份验证仍然不同。

仅官方 Completions 适配器不会将受支持的模型固定到按量计费：旧配置曾将该适配器与 Codex 订阅身份验证一起使用。 当两种凭据类型都符合条件时，自动选择优先选择订阅路由。该偏好不会改变隐式运行时，也不会要求仅为 API 的配置安装 Codex。没有 auth 覆盖的字面提供商 apiKey 在符合条件的配置文件之后仍然是回退。 必需的配置文件绑定、提供商身份验证设置、已配置的密钥引用和显式身份验证顺序仍然优先。编写的 OpenClaw 运行时选择在两种类型都符合条件时优先选择 API 路由；运行时兼容性会独立检查。未固定的心跳和子代理模型继承其默认模型的路由意图。保存模型引用迁移后，Doctor 会报告已解决的计费路由变更，包括消费者以及旧/新模型、路由和配置文件。

openclaw doctor --fix 将旧版 codex/* 和 openai-codex/* 模型引用、旧版 Codex 身份验证配置文件 ID 以及旧版 Codex 身份验证顺序条目迁移到规范的 openai 路由。迁移后的模型引用会获得模型作用域的 agentRuntime.id: "codex"；新的身份验证顺序配置请使用 auth.order.openai。

Agents API MVP¶

独立的 Agents API 插件（@openclaw/agentsapi）与 Codex 插件一起注册显式 agentsapi 框架。OpenAI 提供商插件继续拥有模型路由和 API 密钥身份验证。 在 agents.defaults.model.primary 中选择一个模型，并将其 agents.defaults.models["openai/<model>"].agentRuntime.id 设置为 "agentsapi"。 使用 OpenAI API 密钥身份验证。该框架将配置的模型发送到 Agents API，没有模型允许列表；不支持的模型会返回 API 错误。 执行使用 OpenAI 托管的 Linux 虚拟机。推理遵循配置的 thinking 级别和模型元数据：保留受支持的力度，否则选择下一个更高的受支持力度，如果没有更高的则选择可用最高力度。 所选力度适用于新会话以及现有会话中的后续轮次。adaptive 和省略的原生力度使用模型默认值；更新现有会话会将其力度重置为该默认值。单代理 MVP 不支持 ultra 委托。自动运行时选择保持不变。 启用推理显示时，新会话请求原生摘要。 摘要生成在创建时固定；为现有会话启用它需要重置。原生委托保持禁用。

{
  agents: {
    defaults: {
      model: { primary: "openai/gpt-6-astra" },
      models: {
        "openai/gpt-6-astra": { agentRuntime: { id: "agentsapi" } },
      },
    },
  },
}

如果配置了 plugins.allow，请在 openai 旁边包含 agentsapi。 独立插件会在插件状态中保留原生会话标识符。它使用共享 harness 运行时来处理租约、生成准入、删除回滚、取消、截止时间以及生命周期事件。Agents API 协议事件、原生完成回执和转录投影仍由插件拥有。切换到该包时，请将早期提供商内原型创建的会话重置一次。

受限 API 密钥需要 Agents 和 Responses 的读写权限，以及 Models 的读取权限，以便服务在创建会话时获取所选模型。

Agents API 拥有持久化智能体会话和工作区。OpenClaw 将会话绑定存储在插件 SQLite 状态中，并将助手评论、推理摘要、原生工具调用及结果以及最终文本镜像到其常规转录中。后续消息会复用智能体会话；在运行中的回合期间输入会引导它，而中断会取消其远程回合。/new 和 /reset 会在下一条消息时开始一个新会话。重置和本地会话删除会使绑定退役；Agents API 会保留远程历史和工作区，可通过其 API 进行管理。

创建会话时，OpenClaw 使用与 Codex 相同的工作区准备，以提供有界的 AGENTS.md、SOUL.md、IDENTITY.md、共享的 USER.md，以及所选人员的 users/<profile-id>/USER.md 覆盖层。符合条件的 BOOTSTRAP.md、MEMORY.md 和 bootstrap-hook 文件会作为支持上下文包含在内。现有的 bootstrap 预算、会话隐私规则和轻量模式仍然适用。当启用的记忆工具指向已配置的工作区时，OpenClaw 会提供记忆引用和当前活动记忆插件的召回指引，而不是嵌入根 MEMORY.md 的内容。

这些是来自 Gateway 的指令快照，而不是复制到托管 VM 中的文件。后续回合会保留它们。使用 /new 或 /reset 可在现有会话中获取编辑、更改的个人用户选择或此行为。准备失败发生在远程会话创建和绑定之前，因此下一次尝试可以重试。

harness 会在适用时复用 OpenClaw 的工具感知委派、Skill Workshop、UI、凭据、Git 共同作者以及额外系统指引。每个回合还会通过现有输入载体接收当前日期/时区、活动计算机、可见回复、权限通知和受监视会话上下文。轻量 cron 输入保持不变。

MVP 客户端没有每回合开发者指令载体或指令刷新操作。工作区/人格刷新、Gateway 技能文件访问和技能目录交付、针对此 harness 的插件命令提示注册、提示构建钩子和上下文引擎组装，以及原生 fork 准备均未实现。原生 Codex 项目发现、协作和延迟工具搜索指令不适用于托管 harness。托管文件与 Gateway 工作区保持分离；附件上传和输出传输可独立支持。

如果事件流关闭，harness 会重新订阅，并在接受完成之前协调已保存的回合、已保存的项目和输入回执。它不会重新提交用户的消息。完成需要一个终止根回合和一个空闲原生会话。恢复的项目使用稳定标识以避免重复历史。如果恢复的项目仍在运行，会显示其已保存快照，并抑制含糊的重叠增量，直到权威完成；新项目继续正常流式传输。

当重试保留原生对话时，后续规范事实也可以修复早期终止回合中缺失的工具记录。这些记录会追加到现有历史中，而不会重放进度，也不会在当前尝试中计入早期工作。检索到的命令调用事实可以在执行仍在运行时保存；持久结果需要该项目自身的终止状态。MCP 参数和网页搜索操作会在其项目完成后保存。

在持久评论和推理记录等待检索到的原生历史时，评论保持实时。缺失或未完成的项可能阻止精确排序；终止协调会保留可用的已完成记录，而不是将其丢弃在未解决项之后。主机输入保持其现有转录位置，历史修复会追加而不会重写较早的消息。

原生 token 用量是尽力而为的，并跨所有已准入回合累积，包括被引导后续消息取代的工作。缓存输入和推理 token 仍是独立的使用事实。计费 token 不会确定活动上下文占用；该值仍不可用。已完成、失败和已取消的回合事件可以在已保存回合没有用量时提供用量；harness 会保留该贡献并只报告一次。

原生命令、MCP 调用和网页搜索使用与 Codex harness 相同的活动和输出回调。助手评论保留其文本，因此进度标记可以在命令仍在运行时到达通道。现有通道设置控制输出和推理可见性。

已保存的原生工具项提供规范历史以及可用的命令输出、退出代码、持续时间、参数、MCP 详情和网页搜索操作。即使助手声称成功，缺失的命令退出事实仍保持未知。原生 API 会公开网页搜索活动，但不包含结果正文或片段。此 harness 不提供结构化计划、diff、压缩事件、原生子智能体以及执行前审批或钩子事件。

新的 Agents API 会话会在实时模式下启用内置网页搜索。在启用网页搜索之前创建的会话需要使用 /new 或 /reset 才能获取它。

harness 支持文本、内置网页搜索、原生托管工作区命令，以及主机授权的 OpenClaw 和插件函数。Gateway 函数保留常规工具策略、钩子、当前运行权限和交付回执；shell 和文件操作仍保留在托管 VM 中。当现有插件和配置启用诸如记忆搜索之类的工具时，这些工具可用。OpenClaw 会在向原生会话确认结果之前，在其常规转录中记录主机函数调用、参数、结果和错误状态。

已接受的文件附件会被复制到托管 VM 中的 /workspace/inputs。 后续附件会上传到同一个已连接环境。位于 /workspace/outputs 下已完成的 原生产物会被复制到 OpenClaw 的托管出站媒体中，并附加到最终回复。限制为每个文件 5 MiB、总计 10 MiB，以及每个方向每轮 50 个文件。模型文本不能选择 Gateway 文件路径进行传输。

此 MVP 中的文件传输支持使用原生 Linux 状态存储或 Docker 管理的状态卷的托管 Linux VM， 以及 Linux Gateway。macOS 主机绑定挂载的 Gateway 状态和 Windows Gateway 不在支持范围内。 如果返回的附件缺失，请检查 Gateway 日志和存储配置； 在 macOS 上，请使用 Docker 管理的状态卷。当输出传输失败时，已完成的助手文本仍会保留， 但它可能仍声称已附加文件。 在将传输视为完成之前，请确认附件确实存在。

应用、连接器、图像生成、自定义上下文引擎和自托管 执行器不在本原型范围内。已接受的轮次会被标记为 不可安全重放，因为托管命令或 Gateway 函数可能已经运行。 OpenClaw 可以在临时提供商故障后继续现有会话。

原生 Codex app-server 认证¶

原生 Codex app-server 框架在符合条件的精确官方 HTTPS 路由隐式选择它时， 或在提供商/模型 agentRuntime.id: "codex" 显式选择它时，使用 openai/* 模型引用。 其认证仍然是基于账户的。OpenClaw 按以下顺序选择认证：

1. 针对该 agent 的有序 OpenAI 认证配置，最好位于 auth.order.openai 下。运行 openclaw doctor --fix 以迁移旧版遗留 Codex 认证配置 ID 和认证顺序。
2. 原生 Codex 账户，仅在显式 appServer.homeScope: "user" 选择加入且没有主机凭据或账户选择拥有该路由时使用。 普通 OpenClaw 会话默认使用隔离的 agent 主目录，即使 Codex 已登录也是如此。准备好的 OpenClaw 凭据保留在该主目录中； OpenClaw 永远不会将它们登录到原生用户主目录。
3. 仅针对本地 stdio app-server 启动，并且仅在 app-server 报告没有账户时：CODEX_API_KEY，然后是 OPENAI_API_KEY。

使用用户主目录选择加入时，状态和目录读取会询问 Codex 其原生 登录情况，而不会将凭据导入 OpenClaw 配置。新的认证刷新会观察原生登录 和登出。原生 API 密钥和订阅账户会选择其匹配 路由。模型运行时选择使用与思考 元数据相同的路由和账户；不可用的运行时不能被选择。当你希望使用 OpenClaw 拥有的配置时，显式认证导入仍然可用。

如果你之前依赖自动使用原生 Codex 登录，请使用 openclaw models auth login --provider openai 登录并选择生成的 OpenClaw 配置。在模型设置中选择检测到的 Codex 会重用符合条件的 OpenClaw 凭据 或在测试连接之前打开受支持的 OpenAI 登录流程。已取消 或失败的登录不会提升该路由。如果登录后的验证失败， 选择已保存的登录以重试，而无需再次登录。设置不再仅仅因为存在原生登录就启用 用户主目录共享。现有显式 homeScope: "user" 设置仍然是选择加入；删除该 设置以使用隔离会话。原生会话采用和监督保持不变。现有个人 Codex 历史不会被移动或删除，普通 OpenClaw 会话仍持久保存在每个 agent 的 Codex 主目录中。

默认每个 agent 的 codex-home/auth.json 不是运行时认证存储。如果 你在那里复制或挂载了 Codex CLI 凭据，请在开始原生 Codex 轮次之前将它们导入到该 agent 的 OpenClaw 认证存储中。将 <agent-id> 替换为拥有此 Codex 主目录的已配置 agent：

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 订阅登录不会仅仅因为 gateway 进程也有用于直接 OpenAI 模型或 嵌入的 OPENAI_API_KEY 而被替换。环境变量 API 密钥回退仅适用于本地 stdio 无账户 路径；它永远不会通过 WebSocket app-server 连接发送。当选择 订阅式 Codex 配置时，OpenClaw 还会将 CODEX_API_KEY 和 OPENAI_API_KEY 排除在派生的 stdio app-server 子进程之外， 并通过 app-server 登录 RPC 发送所选凭据。

当该订阅配置被 Codex 使用限制阻止时，OpenClaw 会将该配置标记为阻止，直到 Codex 通告的重置时间，并让认证 顺序轮换到下一个 openai:* 配置，而不改变所选 模型或退出 Codex 框架。一旦重置时间过去，该 订阅配置再次符合条件。

Chat /status 报告来自所选运行时当前 准备账户的认证模式。原生登录与 OpenClaw 配置保持区分；它不 满足不可用的显式配置固定。