智能体运行时
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 运行时:
这意味着 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。
决策树:
- Codex bind/control/thread/resume/steer/stop -> 当内置
codex插件启用时,使用原生/codex命令入口。 - 将 Codex 作为嵌入式运行时,或使用常规的订阅制 Codex Agent 体验 ->
openai/<model>。 - 为 OpenAI 模型明确选择 OpenClaw -> 将模型引用保持为
openai/<model>,并将 provider/model 运行时策略设置为agentRuntime.id: "openclaw"。所选的openaiOAuth 配置文件会在内部通过 OpenClaw 的 Codex-auth 传输通道进行路由。 - 配置中的旧版 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 中移除。 - 明确请求 ACP、acpx 或 Codex ACP 适配器 ->
runtime: "acp"和agentId: "codex"。 - 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 在提供商和模型解析之后解析嵌入式运行时,顺序如下:
- 模型范围运行时策略 优先。它位于已配置的提供商
模型条目中,或位于
agents.defaults.models["provider/model"].agentRuntime/agents.entries.*.models["provider/model"].agentRuntime中。诸如agents.defaults.models["vllm/*"].agentRuntime的提供商 通配符在精确模型策略之后应用,因此动态发现的提供商模型可以 共享一个运行时,而不会覆盖精确的逐模型例外。 - 提供商范围运行时策略:
models.providers.<provider>.agentRuntime。 auto模式:已注册的插件运行时可以声明受支持的提供商/模型对。- 如果在
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 能够从已配置路由中确定时,下一轮运行时元数据会包含已声明的回退。它不会检查凭据或启动运行时;最终路由/身份验证准备仍可能拒绝该轮次。已完成的结果会记录实际运行的运行时。
相关¶
- Codex 测试框架
- Codex 测试框架运行时
- GitHub Copilot 代理运行时
- OpenAI
- 代理测试框架插件
- 代理循环
- 模型
- 状态
- Code Mode — 一个实验性代理运行时功能,支持按模型自动激活
- 代理运行时架构 — 代码布局、模块边界以及内置运行时的选择方式
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw