智能体运行时

agent runtime（代理运行时）拥有一个已准备好的模型循环：它接收提示词，驱动模型输出，处理原生工具调用，并将完成的回合返回给 OpenClaw。

运行时容易与提供方（provider）混淆，因为两者都出现在模型配置附近。它们是不同层级：

harness 是提供代理运行时的实现（代码术语）。例如，内置的 Codex harness 实现了 codex 运行时。公共配置在提供方或模型条目上使用 agentRuntime.id；整代理运行时键是遗留项，会被忽略。openclaw doctor --fix 会移除旧的整代理运行时固定项，并将遗留的运行时模型引用重写为规范的提供方/模型引用，在需要时还会加上模型作用域的运行时策略。

两类运行时：

• 嵌入式 harness 在 OpenClaw 已准备的代理循环内运行：内置的 openclaw 运行时，以及已注册的插件 harness，例如 codex 和 copilot。
• CLI 后端运行本地 CLI 进程，同时保持模型引用为规范形式。例如，anthropic/claude-opus-5 配合模型作用域的 agentRuntime.id: "claude-cli" 表示“选择 Anthropic 模型，通过 Claude CLI 执行”。claude-cli 不是嵌入式 harness id，绝不能传给 AgentHarness 选择。

copilot harness 是一个独立的、可选启用的外部插件 harness，用于 GitHub Copilot CLI；关于用户如何在 PI、Codex 和 GitHub Copilot 代理运行时之间进行选择，请参阅 GitHub Copilot 代理运行时。

Codex 形态¶

Codex 这一名称出现在多种形态中：

这些形态是刻意相互独立的。启用 codex 插件即可获得原生 app-server 功能；openclaw doctor --fix 负责修复遗留 Codex 路由和清理过期的会话固定项。自动选择 Codex 需要一条兼容的有效路由：精确的官方 HTTPS Platform Responses 或 ChatGPT Responses 端点，且没有自定义请求覆盖。仅凭 openai/* 前缀并不会选择 Codex。

常见的 ChatGPT/Codex 订阅设置使用 Codex OAuth 进行认证，但保持模型引用为 openai/*，并选择 codex 运行时：

{
  agents: {
    defaults: {
      model: "openai/gpt-6-astra",
    },
  },
}

这意味着 OpenClaw 选择一个 OpenAI 模型引用，然后请求 Codex app-server 运行时来运行嵌入式代理回合。它不表示“使用 API 计费”，也不表示渠道、模型提供方目录或 OpenClaw 会话存储会变成 Codex。

当内置 codex 插件启用时，请使用原生 /codex 命令形态（/codex bind、/codex threads、/codex resume、/codex steer、/codex stop）进行自然语言 Codex 控制，而不是 ACP。仅当用户明确要求使用 ACP/acpx 或正在测试 ACP 适配器路径时，才对 Codex 使用 ACP。Claude Code、Gemini CLI、OpenCode、Cursor 及类似的外部 harness 仍然使用 ACP。

决策树：

1. Codex bind/control/thread/resume/steer/stop -> 当内置 codex 插件启用时，使用原生 /codex 命令形态。
2. 将 Codex 作为嵌入式运行时，或使用常规订阅支持的 Codex 代理体验 -> openai/<model>。
3. 针对 OpenAI 模型明确选择 OpenClaw -> 保持模型引用为 openai/<model>，并将提供方/模型运行时策略设置为 agentRuntime.id: "openclaw"。所选的 openai OAuth 配置文件会在内部通过 OpenClaw 的 Codex-auth 传输进行路由。
4. 配置中的遗留 Codex 模型引用 -> 使用 openclaw doctor --fix 修复为 openai/<model>；doctor 会通过添加提供方/模型作用域的 agentRuntime.id: "codex"（在旧模型引用隐含该设置的位置）来保留 Codex 认证路由。遗留的 codex-cli/* 模型引用也会修复到相同的 openai/<model> Codex app-server 路由；内置的 Codex CLI 后端已在 v2026.5.14 中移除。
5. 明确要求 ACP、acpx 或 Codex ACP 适配器 -> runtime: "acp" 和 agentId: "codex"。
6. Claude Code、Gemini CLI、OpenCode、Cursor、Droid 或其他外部 harness -> 使用 ACP/acpx，而非原生子代理运行时。

有关 OpenAI 系列前缀拆分，请参阅 OpenAI 和 模型提供商。有关 Codex 运行时支持契约，请参阅 Codex harness 运行时。

运行时所有权¶

不同的运行时负责循环的不同部分：

设计规则：如果 OpenClaw 拥有该层面，它可以提供正常的插件钩子 行为。如果原生运行时拥有该层面，OpenClaw 需要运行时 事件或原生钩子。如果原生运行时拥有规范线程状态， OpenClaw 会镜像并投射上下文，而不是重写不支持的 内部实现。

一个锁定的具体模型聊天仍使用正常的模型发现、凭据 选择及其配置的请求传输。锁定会阻止模型 更改；它不会将模型或认证所有权交给原生 运行时。Responses 参数和其他已编写的请求设置仍是具体 请求的一部分。所选运行时必须支持它们，或在执行前声明无损 回退。

一个绑定的原生会话则可以保留其原生模型，并单独 保留其原生连接的认证。OpenClaw 会针对精确固定的 harness 及其私有绑定来验证该所有权， 而不是依据先前的使用报告。 对于 Codex，原生认证仅属于独立的监督 连接；在受管连接上保留原生模型仍会使用主机 认证准备。原生认证连接保留其自身的连接策略， 并且不会收到转发的主机配置文件。它们会拒绝显式的每次运行提供商 流参数，而不是静默丢弃这些参数。当你需要应用这些参数时，请使用具体模型聊天。

当原生模型仍使用主机认证时，其实际的提供商/模型 对控制凭据和请求准备，而不是外层默认值。显式 认证配置文件保持锁定。如果恢复操作在凭据准备之后更改了该对，则回合会在推理前停止，并保留新观察到的 原生状态；它不会使用过期凭据重试，也不会替换线程。

会话行和事件使用原生所有者的已知模型对。待处理的原生 分支可以显示已配置的占位符，直到其第一个回合选择模型。 对于原生认证会话，聊天元数据会从该渲染行中移除无关的主机凭据门控， 而不会声称原生凭据已就绪。全局模型 可用性和具体模型聊天保留其正常的主机认证检查。原生 选择也独立于最终响应的计费模型，包括 当主机终结器提供最后一个答案时。

运行时选择¶

OpenClaw 在提供商和模型解析之后解析嵌入式运行时， 顺序如下：

1. 模型范围的运行时策略优先。它位于已配置的提供商 模型条目中，或位于 agents.defaults.models["provider/model"].agentRuntime / agents.entries.*.models["provider/model"].agentRuntime。像 agents.defaults.models["vllm/*"].agentRuntime 这样的提供商通配符 在精确模型策略之后应用，因此动态发现的提供商模型 可以共享一个运行时，而不会覆盖精确的逐模型例外。
2. 提供商范围的运行时策略：models.providers.<provider>.agentRuntime。
3. auto 模式：已注册的插件运行时可以声明受支持的提供商/模型对。
4. 如果在 auto 模式下没有任何运行时声明该回合，OpenClaw 会回退到 openclaw 作为兼容性运行时。当运行必须严格时，请使用显式运行时 id。

历史 agentHarnessId 记录哪个运行时生成了转录；它 不会固定下一个回合。显式可信的 pluginOwnerId 即使在另一个 harness 报告使用后，仍保持为 会话的控制所有者。对该插件拥有的聊天上的模型锁定 不会将该观察结果变为原生 harness 固定。锁定的原生转录保留其创建 harness，并且兼容的 显式会话运行时覆盖优先于已配置策略。 ACP 会话保留其 ACP 后端。旧的整体代理运行时配置和 OPENCLAW_AGENT_RUNTIME 会被忽略；使用 openclaw doctor --fix 移除过期 配置并修复旧模型引用。

显式提供商/模型插件运行时在执行框架缺失，或无法支持路由或身份验证时失败关闭。选择时有一个例外：执行框架可以声明 OpenClaw 能够复现完全相同的请求。Codex 对已编写的请求覆盖（例如请求头、请求参数、超时或负载兼容性开关）使用此回退。它会保留这些设置，而不是静默丢弃它们。一旦执行框架开始执行，其失败不会通过另一个运行时重放。

肯定的 compat.supportsReasoningEffort: true 以及一个非空的 compat.supportedReasoningEfforts 列表，其中仅包含 minimal、low、medium、high、xhigh、max 或 ultra，用于描述原生推理能力；它们不会将一个原本兼容的路由排除出 Codex。禁用推理、自定义 effort 标签以及其他兼容性开关仍属于请求行为。模型级运行时控制（例如 fastMode 和 thinking）在值有效时也会保留原生选择。

CLI 后端别名不同于嵌入式执行框架 ID。首选 Claude CLI 形式：

{
  agents: {
    defaults: {
      model: "anthropic/claude-opus-5",
      models: {
        "anthropic/claude-opus-5": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}

诸如 claude-cli/claude-opus-4-7 之类的旧版引用可作为兼容性输入接受，但新配置应保持提供商/模型规范形式，并将执行后端放入提供商/模型运行时策略中。运行 openclaw doctor --fix 可将持久化的旧版模型选择、模型映射键以及显式 modelPolicy.allow 条目重写为该规范形式。

旧版 codex-cli/* 引用有所不同：doctor 会将其迁移到 openai/*，使其通过 Codex app-server 执行框架运行，而不是保留 Codex CLI 后端。

对于 OpenAI 代理模型，未设置的运行时和 auto 可以在提供商拥有的有效路由声明其兼容时选择 Codex。自定义端点、Completions 适配器以及已编写的请求覆盖会保留在 OpenClaw 上，而不是丢失其传输设置。显式 agentRuntime.id: "openclaw" 也会保留内置运行时可用；当选择了 openai OAuth 配置文件时，它会使用 OpenClaw 的 Codex-auth 传输，同时保持公共模型引用为 openai/*。过时的历史生产者字段不会固定下一轮，并可通过 openclaw doctor --fix 清理。

如果 openclaw doctor 警告 codex 插件已启用，但配置中仍存在旧版 Codex 模型引用，请将其视为旧版路由状态，并运行 openclaw doctor --fix 将其重写为带有 Codex 运行时的 openai/*。

GitHub Copilot 代理运行时¶

外部 @openclaw/copilot 插件注册了一个选择加入的 copilot 运行时，由 GitHub Copilot CLI（@github/copilot-sdk）提供支持。它声明规范的订阅提供商 github-copilot，并且从不被 auto 选择。可通过 agentRuntime.id 按模型或按提供商选择加入：

{
  agents: {
    defaults: {
      model: "github-copilot/gpt-5.5",
      models: {
        "github-copilot/gpt-5.5": {
          agentRuntime: { id: "copilot" },
        },
      },
    },
  },
}

插件清单声明了执行框架提供商、运行时、CLI 会话键和身份验证配置文件前缀，无需 openclaw doctor 加载插件代码。有关配置、身份验证、转录镜像、压缩、声明式 doctor 契约，以及更广泛的 PI、Codex 与 Copilot SDK 之间的决策，请参阅 GitHub Copilot 代理运行时。

兼容性契约¶

当运行时不是 OpenClaw 时，其文档应说明它支持哪些 OpenClaw 接口：

Codex 运行时支持契约记录在 Codex 执行框架运行时 中。

状态标签¶

状态输出可以同时显示 Execution 和 Runtime 标签。请将它们视为诊断信息，而不是提供商名称：

• 诸如 openai/gpt-6-astra 的模型引用是所选的提供商/模型。
• 诸如 codex 的运行时 ID 是执行该轮次的循环。
• 诸如 Telegram 或 Discord 的频道标签是对话发生的位置。

如果某次运行显示了意外的运行时，请先检查所选提供商/模型运行时策略。当已注册执行框架能够从配置的路由中确定时，下一轮运行时元数据会包含已声明的回退。它不会探测凭据或启动运行时；最终路由/身份验证准备仍可能拒绝该轮次。已完成的结果会记录实际运行的运行时。

相关¶

• Codex harness
• Codex harness runtime
• GitHub Copilot agent runtime
• OpenAI
• Agent harness 插件
• Agent 循环
• 模型
• 状态
• Code Mode — 一个实验性的 Agent 运行时功能，支持按模型自动激活
• Agent 运行时架构 — 代码布局、模块边界以及内置运行时的选择方式