本页内容
本页内容
代理运行时
代理运行时
代理运行时负责一个已准备好的模型循环:它接收提示词, 驱动模型输出,处理原生工具调用,并将完成的轮次返回给 OpenClaw。
运行时很容易与提供方混淆,因为它们都会出现在模型配置附近。它们属于不同层:
| 层 | 示例 | 含义 |
|---|---|---|
| 提供者 | anthropic, github-copilot, openai |
OpenClaw 如何进行身份验证、发现模型以及命名模型引用。 |
| 模型 | claude-opus-4-6, gpt-6-astra |
为代理轮次选择的模型。 |
| 代理运行时 | claude-cli, codex, copilot, muse, openclaw |
执行已准备轮次的底层循环或后端。 |
| 渠道 | Discord, Slack, Telegram, WhatsApp | 消息进入和离开 OpenClaw 的位置。 |
harness 是提供代理运行时(代码术语)的实现。例如,捆绑的 Codex harness实现了 codex 运行时。公共配置在提供者或模型条目上使用 agentRuntime.id;整个代理运行时密钥是遗留的并且被忽略。 openclaw doctor --fix 删除了旧的全代理运行时引脚,并将遗留运行时模型引用重写为标准 provider/model 引用以及模型范围的运行时策略(如果需要)。
有两类运行时:
- 嵌入式工具在OpenClaw准备好的代理循环内运行:内置
openclaw运行时,加上注册的插件工具,例如codex、copilot和muse。 - CLI 后端 运行本地 CLI 进程,同时保持模型引用为其标准形式。例如,
anthropic/claude-opus-5和模型范围的agentRuntime.id: "claude-cli"表示“选择 Anthropic 模型,通过 Claude CLI 执行”。claude-cli不是嵌入式harness ID,不得传递给 AgentHarness 选择。
copilot harness是用于 GitHub Copilot CLI 的独立的、可选的外部插件harness;请参阅 GitHub Copilot 代理运行时,了解 PI、Codex 和 GitHub Copilot 代理运行时之间面向用户的决策。
Codex 表面
多个表面共用 Codex 这一名称:
| 表面 | OpenClaw name/config | 它的作用 |
|---|---|---|
| 本机 Codex 应用程序服务器运行时 | openai/* 模型参考 |
通过 Codex 应用程序服务器运行 OpenAI 嵌入式代理。这是常见的 ChatGPT/Codex 订阅设置。 |
| Codex OAuth 身份验证配置文件 | openai OAuth 配置文件 |
存储 Codex 应用程序服务器harness使用的 ChatGPT/Codex 订阅身份验证。 |
| Codex ACP 适配器 | runtime: "acp", agentId: "codex" |
通过外部 ACP/acpx 控制平面运行 Codex。仅当明确要求 ACP/acpx 时才使用。 |
| 原生 Codex 聊天控制命令集 | /codex ... |
从聊天中绑定、恢复、引导、停止并检查 Codex app-server 线程。 |
| OpenAI 平台 API 非代理表面路线 | openai/* 加 API-key 身份验证 |
直接 OpenAI API,例如图像、嵌入、语音和实时。 |
这些表面是有意独立的。启用 codex 插件使本机应用程序服务器功能可用; openclaw doctor --fix 拥有旧版 Codex 路由修复和过时会话引脚清理。自动 Codex 选择需要兼容的有效路由:精确的官方 HTTPS 平台响应或 ChatGPT 响应端点,无需编写请求覆盖。仅 openai/* 前缀不会选择 Codex。
常见的 ChatGPT/Codex 订阅设置使用 Codex OAuth 进行认证,但将模型引用保持为 openai/*,并选择 codex 运行时:
这意味着 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 适配器路径时,才将 ACP 用于 Codex。 Claude Code、Gemini、CLI、OpenCode、Cursor 和类似的外部harness仍使用 ACP。
决策树:
- Codex bind/control/thread/resume/steer/stop -> 当启用捆绑的
codex插件时,本机/codex命令界面。 - 将 Codex 作为嵌入式运行时,或使用通常由订阅支持的 Codex 代理体验 ->
openai/<model>。 - OpenClaw 为 OpenAI 模型明确选择 -> 将模型引用保留为
openai/<model>并将 provider/model 运行时策略设置为agentRuntime.id: "openclaw"。选定的openaiOAuth 配置文件通过 OpenClaw 的 Codex-auth 传输进行内部路由。 - 配置中的旧版 Codex 模型参考 -> 使用
openclaw doctor --fix修复为openai/<model>; doctor 通过在旧模型引用暗示的位置添加 provider/model-scopedagentRuntime.id: "codex"来保留 Codex 身份验证路线。旧版codex-cli/*模型引用修复到相同的openai/<model>Codex 应用程序服务器路由;捆绑的 Codex CLI 后端已在 v2026.5.14. 中删除 - 明确请求 ACP、acpx 或 Codex ACP 适配器 ->
runtime: "acp"andagentId: "codex"。 - Claude Code、Gemini CLI、OpenCode、Cursor、Droid 或其他外部 harness -> 使用 ACP/acpx,而不是原生子代理运行时。
| 你mean... | Use... |
|---|---|
| Codex 应用服务器 chat/thread 控制 | 来自捆绑的 codex 插件的 /codex ... |
| Codex app-server 嵌入式代理运行时 | openai/* 代理模型引用 |
| OpenAI Codex OAuth | openai OAuth 配置文件 |
| Claude Code 或其他外部 harness | ACP/acpx |
有关 OpenAI- 系列前缀拆分,请参阅 OpenAI 和 模型提供程序。有关 Codex 运行时支持合同,请参阅 Codex Harness Runtime。
运行时所有权
不同的运行时拥有循环的不同部分:
| 表面 | OpenClaw 嵌入式 | Codex 应用服务器 |
|---|---|---|
| 模型循环所有者 | OpenClaw,通过 OpenClaw 嵌入式运行器 | Codex 应用服务器 |
| 主线程状态 | OpenClaw 对话记录 | Codex 线程,以及 OpenClaw 对话记录镜像 |
| OpenClaw 动态工具 | 原生 OpenClaw 工具循环 | 通过 Codex 适配器桥接 |
| 本机 shell 和文件工具 | OpenClaw路径 | Codex-native 工具,通过支持的本机挂钩桥接 |
| 上下文引擎 | 原生 OpenClaw 上下文组装 | OpenClaw 项目将上下文组装到 Codex 回合中 |
| 压缩 | OpenClaw 或选定的上下文引擎 | Codex-native 压缩,具有 OpenClaw 通知和镜像维护 |
| 通道传递 | OpenClaw | OpenClaw |
设计规则:如果OpenClaw拥有该表面,则它可以提供正常的插件挂钩行为。如果本机运行时拥有该表面,则 OpenClaw 需要运行时事件或本机挂钩。如果本机运行时拥有主线程状态,则 OpenClaw 镜像并投影上下文,而不是重写不支持的内部结构。
锁定的具体模型聊天仍然使用正常的模型发现、凭证选择及其配置的请求传输。锁可防止模型更改;它不会将模型或身份验证所有权移交给本机运行时。响应参数和其他创作的请求设置仍然是具体请求的一部分。所选运行时必须支持它们或在执行前声明无损回退。
bound 本机会话 可以改为保留其本机模型,并单独保留其本机连接的身份验证。 OpenClaw 根据确切的固定harness及其私人绑定验证所有权,而不是以前的使用报告。对于Codex,本机认证仅属于单独的监管连接;在托管连接上保留本机模型仍然使用主机身份验证准备。本机身份验证连接保留自己的连接策略,并且不接收转发的主机配置文件。它们拒绝显式的每次运行提供程序流参数,而不是默默地删除它们。当您需要应用这些参数时,请使用具体模型聊天。
当本机模型仍然使用主机身份验证时,其实际的 provider/model 对控制凭据和请求准备,而不是外部默认值。显式身份验证配置文件保持锁定状态。如果在准备好凭据后恢复更改了该对,则轮流会在推理之前停止并保留新观察到的本机状态;它不会使用过时的凭据重试或替换线程。
会话行和事件使用本机所有者的已知模型对。待处理的本机分支可以显示配置的占位符,直到其第一次选择模型。对于本机身份验证会话,聊天元数据会从呈现的行中删除不相关的主机凭据门,而不声明本机凭据已准备就绪。全局模型可用性和具体模型聊天保持正常的主机身份验证检查。本机选择也与最终响应的计费模型保持分离,包括主机终结器何时提供最后的答案。
运行时选择
OpenClaw 在提供者和模型解析之后按以下顺序解析嵌入式运行时:
- 模型范围的运行时策略 优先。它位于已配置的提供者模型条目中,或位于
agents.defaults.models["provider/model"].agentRuntime/agents.entries.*.models["provider/model"].agentRuntime。像agents.defaults.models["vllm/*"].agentRuntime这样的提供者通配符会在精确模型策略之后生效,因此动态发现的提供者模型可以共享同一个运行时,而不会覆盖精确到单个模型的例外。 - 提供者范围的运行时策略:
models.providers.<provider>.agentRuntime。 auto模式:注册的插件运行时可以声明支持的 provider/model 对。- 如果在
auto模式下没有任何项声明该轮次,OpenClaw 会回退到openclaw作为兼容运行时。若运行必须严格一致,请使用显式的运行时 id。
历史agentHarnessId记录了哪个运行时产生了转录本;它不会固定下一回合。即使在另一个工具报告使用情况后,显式受信任的 pluginOwnerId 仍然是会话的控制所有者。该插件拥有的聊天上的模型锁定不会将观察结果转换为本机harness引脚。锁定的本机转录保留其创建工具,并且兼容的显式会话运行时覆盖优先于配置的策略。 ACP 会话保留其 ACP 后端。旧版整体代理运行时配置和 OPENCLAW_AGENT_RUNTIME 被忽略;使用 openclaw doctor --fix 删除过时的配置并修复旧模型引用。
当harness丢失或无法支持路由或身份验证时,显式 provider/model 插件运行时拒绝运行。有一个选择时例外:harness可能会声明 OpenClaw 可以重现确切的请求。 Codex 使用此回退来编写请求覆盖,例如标头、请求参数、超时或有效负载兼容性开关。它会保留这些设置,而不是默默地删除它们。一旦工具开始执行,它的失败就不会通过另一个运行时重播。
肯定的 compat.supportsReasoningEffort: true 和仅包含 minimal、low、medium、high、xhigh、max 的非空 compat.supportedReasoningEfforts 列表,或ultra 描述本机推理能力;他们不会选择 Codex 之外的其他兼容路线。禁用推理、自定义工作标签和其他兼容性开关仍然是请求行为。模型级运行时控件(例如 fastMode 和 thinking)在其值有效时也会保留本机选择。
CLI 后端别名与嵌入式 harness ids 不同。首选的 Claude CLI 形式如下:
诸如 claude-cli/claude-opus-4-7 之类的旧参考被接受作为兼容性输入,但新配置应将 provider/model 保持其标准形式,并将执行后端置于 provider/model 运行时策略中。运行 openclaw doctor --fix 将持久保留的旧模型选择、模型映射键和显式 modelPolicy.allow 条目重写为该标准形状。
旧的 codex-cli/* 引用有所不同:doctor 会将它们迁移到 openai/*,使其通过 Codex app-server harness 运行,而不是保留一个 Codex CLI 后端。
对于OpenAI代理模型,未设置运行时和auto可以在提供商拥有的有效路由声明兼容时选择Codex。自定义端点、完成适配器和编写的请求覆盖保留在 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 插件注册由 GitHub Copilot CLI (@github/copilot-sdk) 支持的选择加入 copilot 运行时。它声称是标准订阅github-copilot提供商,并且是auto选择的never。通过 agentRuntime.id 选择按模型或按提供商:
插件清单声明了 harness 提供商、运行时、CLI 会话密钥和身份验证配置文件前缀, 无需 openclaw doctor 加载插件代码。有关配置、身份验证、记录镜像、压缩、 声明式 doctor 契约,以及更广泛的 PI、Codex 与 Copilot SDK 选型,请参阅 GitHub Copilot 代理运行时。
Muse 代码代理运行时
外部 @openclaw/muse 插件为标准 meta 提供程序注册由 Muse 代码 CLI 支持的选择加入 muse 运行时。 auto 从未选择过它;在 meta/* 模型或提供程序上设置 agentRuntime.id: "muse"。请参阅 Muse 代码代理运行时。
兼容性契约
当运行时不是 OpenClaw 时,其文档应说明它支持哪些 OpenClaw 表面:
| 问题 | 重要原因 |
|---|---|
| 谁拥有模型循环? | 决定重试、工具续接以及最终答案决策发生在哪里。 |
| 谁拥有主线程历史记录? | 决定 OpenClaw 是否可以编辑历史,还是只能镜像它。 |
| OpenClaw 动态工具有用吗? | 消息、会话、cron 和 OpenClaw- 拥有的工具依赖于此。 |
| 动态工具挂钩有用吗? | 插件需要 before_tool_call、after_tool_call 以及围绕 OpenClaw- 拥有的工具的中间件。 |
| 原生工具钩子是否可用? | Shell、patch 以及运行时拥有的工具需要原生钩子支持以进行策略和观察。 |
| 上下文引擎生命周期是否运行? | 内存和上下文插件依赖 assemble、ingest、after-turn 和 compaction 生命周期。 |
| 暴露了哪些压缩数据? | 有些插件只需要通知;其他人需要 kept/dropped 元数据。 |
| 哪些内容是有意不支持的? | 用户不应假定在原生运行时拥有更多状态的情况下与 OpenClaw 等价。 |
Codex 运行时支持契约记录在 Codex harness runtime。
状态标签
状态输出可以同时显示 Execution 和 Runtime 标签。请将它们视为诊断信息,而不是提供方名称:
- A 模型参考(例如
openai/gpt-6-astra)是所选的 provider/model. - A运行时id例如
codex是执行回合的循环。 - 类似 Telegram 或 Discord 的频道标签表示对话发生的位置。
如果运行显示意外的运行时,请首先检查所选的 provider/model 运行时策略。当注册的harness可以从配置的路线确定它时,下一回合运行时元数据包括声明的后备。它不检查凭据或启动运行时;最终route/auth准备依然可以拒绝回合。完成的结果记录了实际运行的运行时间。
相关内容
- Codex 运行环境
- Codex harness运行时
- GitHub Copilot 代理运行时
- Muse 代码代理运行时
- OpenAI
- Agent harness 插件
- 代理回路
- 模型
- 状态
- Code Mode — 一种实验性代理运行时功能,可自动按模型激活
- Agent 运行时架构 — 代码布局、模块边界以及如何选择内置运行时