跳转至

智能体运行时

Agent 运行时负责一个已准备的模型循环:它接收 Prompt,驱动模型输出,处理原生工具调用,并将完成的回合返回给 OpenClaw。

运行时很容易与 Provider 混淆,因为两者都出现在模型配置附近。它们是不同的层:

层 示例 含义
Provider anthropic, github-copilot, openai OpenClaw 如何进行身份验证、发现模型以及命名模型引用。
模型 claude-opus-4-6, gpt-6-astra 为 Agent 回合选定的模型。
Agent 运行时 claude-cli, codex, copilot, openclaw 执行已准备回合的底层循环或后端。
渠道 Discord, Slack, Telegram, WhatsApp 消息进出 OpenClaw 的地方。

harness 是提供 Agent 运行时的实现(代码术语)。例如,内置的 Codex harness 实现了 codex 运行时。公共配置在 provider 或 model 条目上使用 agentRuntime.id;整 Agent 级运行时键已废弃并被忽略。openclaw doctor --fix 会移除旧的整 Agent 运行时固定配置,并将遗留的运行时模型引用改写为规范的 provider/model 引用,并在需要时附加模型级运行时策略。

运行时分为两类:

  • 嵌入式 harness 在 OpenClaw 已准备的 Agent 循环内运行:内置的 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 agent runtime 之间的选择,请参阅 GitHub Copilot agent runtime。

Codex 入口

有多个入口共享 Codex 这个名称:

使用入口 OpenClaw 名称/配置 作用
原生 Codex app-server 运行时 openai/* 模型引用 通过 Codex app-server 运行 OpenAI 嵌入式 Agent 回合。这是常见的 ChatGPT/Codex 订阅设置。
Codex OAuth 认证配置文件 openai OAuth 配置文件 存储 ChatGPT/Codex 订阅认证,供 Codex app-server harness 使用。
Codex ACP 适配器 runtime: "acp", agentId: "codex" 通过外部 ACP/acpx 控制平面运行 Codex。仅在明确要求使用 ACP/acpx 时使用。
原生 Codex 聊天控制命令集 /codex ... 在聊天中绑定、恢复、引导、停止和检查 Codex app-server 线程。
面向非 Agent 入口的 OpenAI Platform API 路由 openai/* 加上 API 密钥认证 直接调用 OpenAI API,例如图像、embeddings、语音和实时(realtime)。

这些入口刻意保持相互独立。启用 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 运行时来运行嵌入式 Agent 回合。这不意味着“使用 API 计费”,也不意味着渠道、模型 Provider 目录或 OpenClaw 会话存储会变成 Codex。

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

决策树:

  1. Codex bind/control/thread/resume/steer/stop -> 当内置 codex 插件启用时,使用原生 /codex 命令入口。
  2. 将 Codex 作为嵌入式运行时,或使用常规的订阅制 Codex Agent 体验 -> openai/<model>。
  3. 为 OpenAI 模型明确选择 OpenClaw -> 将模型引用保持为 openai/<model>,并将 provider/model 运行时策略设置为 agentRuntime.id: "openclaw"。所选的 openai OAuth 配置文件会在内部通过 OpenClaw 的 Codex-auth 传输通道进行路由。
  4. 配置中的旧版 Codex 模型引用 -> 使用 openclaw doctor --fix 修复为 openai/<model>;doctor 会在旧模型引用隐含该路由的位置添加 provider/model 级 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,而不是原生子 Agent 运行时。
你的意思是... 请使用...
Codex app-server 聊天/线程控制 /codex ...,来自捆绑的 codex 插件
Codex app-server 嵌入式代理运行时 openai/* 代理模型引用
OpenAI Codex OAuth openai OAuth 配置文件
Claude Code 或其他外部 harness ACP/acpx

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

运行时所有权

不同的运行时拥有循环的不同部分:

方面 OpenClaw 嵌入式 Codex app-server
模型循环所有者 OpenClaw,通过 OpenClaw 嵌入式运行器 Codex app-server
规范线程状态 OpenClaw 转录 Codex 线程,外加 OpenClaw 转录镜像
OpenClaw 动态工具 原生 OpenClaw 工具循环 通过 Codex 适配器桥接
原生 shell 和文件工具 OpenClaw 路径 Codex 原生工具,在受支持时通过原生钩子桥接
上下文引擎 原生 OpenClaw 上下文组装 OpenClaw 将组装的上下文投射到 Codex 回合
压缩 OpenClaw 或所选上下文引擎 Codex 原生压缩,附带 OpenClaw 通知和镜像维护
通道投递 OpenClaw OpenClaw

设计规则:如果 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 移除过期 配置并修复旧模型引用。

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

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

CLI 后端别名不同于嵌入式 harness 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 之类的旧版引用可作为兼容性输入接受,但新配置应保持 provider/model 规范形式,并将执行后端放在 provider/model 运行时策略中。运行 openclaw doctor --fix 可将已持久化的旧版模型选择、model-map 键以及显式 modelPolicy.allow 条目重写为该规范形式。

旧版 codex-cli/* 引用有所不同:doctor 会将它们迁移为 openai/*,使其通过 Codex app-server harness 运行,而不是保留 Codex CLI 后端。

对于 OpenAI 代理模型,未设置的运行时和 auto 可以在 provider 拥有的有效路由声明其兼容时选择 Codex。自定义端点、Completions 适配器以及手工编写的请求覆盖会保留在 OpenClaw 上,而不是丢失其传输设置。显式 agentRuntime.id: "openclaw" 也会保留内置运行时可用;当选择了 openai OAuth 配置文件时,它使用 OpenClaw 的 Codex-auth 传输,同时保持公开模型引用为 openai/*。过时的历史 producer 字段不会固定下一轮,并可通过 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 provider,并且永远不会被 auto 选择。通过 agentRuntime.id 按模型或按 provider 选择加入:

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

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

兼容性契约

当运行时不是 OpenClaw 时,其文档应说明它支持哪些 OpenClaw 方面:

问题 为什么重要
谁拥有模型循环? 决定重试、工具延续和最终答案决策发生在哪里。
谁拥有规范线程历史? 决定 OpenClaw 可以编辑历史还是只能镜像它。
OpenClaw 动态工具是否可用? 消息、会话、cron 和 OpenClaw 拥有的工具依赖于此。
动态工具钩子是否可用? 插件期望在 OpenClaw 拥有的工具周围有 before_tool_call、after_tool_call 和中间件。
原生工具钩子是否可用? Shell、patch 和运行时拥有的工具需要原生钩子支持以实现策略和观察。
上下文引擎生命周期是否运行? 内存和上下文插件依赖 assemble、ingest、after-turn 和 compaction 生命周期。
暴露哪些压缩数据? 一些插件只需要通知;其他插件需要保留/丢弃元数据。
哪些内容被有意不支持? 当原生运行时拥有更多状态时,用户不应假设 OpenClaw 等价性。

Codex 运行时支持契约记录在 Codex harness 运行时 中。

状态标签

状态输出可以同时显示 Execution 和 Runtime 标签。将它们视为诊断信息,而不是 provider 名称:

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

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw