Agent Runtimes

智能体运行时负责一个已准备好的模型循环：它接收提示词、驱动模型输出、处理原生工具调用，并将完成的轮次返回给 OpenClaw。

运行时很容易与提供商混淆，因为两者都会出现在模型配置附近。它们属于不同的层：

Harness 是提供智能体运行时的实现（代码术语）。例如，内置的 Codex harness 实现了 codex 运行时。公共配置在提供商或模型条目中使用 agentRuntime.id；整个智能体级别的运行时键属于旧版配置，会被忽略。openclaw doctor --fix 会移除旧的整个智能体级别运行时固定配置，并将旧版运行时模型引用重写为规范的提供商/模型引用，同时在需要时添加模型级运行时策略。

运行时分为两个系列：

• 嵌入式 harness 在 OpenClaw 已准备好的智能体循环内运行：包括内置的 openclaw 运行时，以及已注册的插件 harness，例如 codex 和 copilot。
• CLI 后端 会运行本地 CLI 进程，同时保持模型引用的规范形式。例如，anthropic/claude-opus-4-8 搭配模型级 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 名称：

这些接口有意彼此独立。启用 codex 插件会提供原生 app-server 功能；openclaw doctor --fix 负责修复旧版 Codex 路由并清理过时的会话固定配置。现在，为智能体模型选择 openai/* 意味着“通过 Codex 运行此模型”，除非使用的是非智能体 OpenAI API 接口。

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

{  agents: {    defaults: {      model: "openai/gpt-5.6-sol",    },  },}

这意味着 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 绑定/控制/线程/恢复/Steer/停止 -> 启用内置 codex 插件时，使用原生 /codex 命令接口。
2. 将 Codex 用作嵌入式运行时或使用常规的订阅支持型 Codex 智能体体验 -> openai/<model>。
3. 为 OpenAI 模型明确选择 OpenClaw -> 将模型引用保留为 openai/<model>，并将提供商/模型运行时策略设置为 agentRuntime.id: "openclaw"。所选的 openai OAuth 配置文件会通过 OpenClaw 的 Codex 身份验证传输层在内部进行路由。
4. 配置中的旧版 Codex 模型引用 -> 使用 openclaw doctor --fix 修复为 openai/<model>；如果旧模型引用隐含使用 Codex 身份验证路由，Doctor 会通过添加提供商/模型级 agentRuntime.id: "codex" 来保留该路由。旧版 codex-cli/* 模型引用会修复到相同的 openai/<model> Codex app-server 路由；OpenClaw 不再保留内置的 Codex CLI 后端。
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 runtime。

运行时所有权

不同运行时负责不同范围的循环：

设计规则：如果某个接口由 OpenClaw 所有，它便可以提供常规插件钩子行为。如果该接口由原生运行时所有，OpenClaw 就需要运行时事件或原生钩子。如果规范线程状态由原生运行时所有，OpenClaw 会镜像并投射上下文，而不是重写不受支持的内部状态。

运行时选择

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

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

整个会话级别和整个智能体级别的运行时固定配置会被忽略：包括 OPENCLAW_AGENT_RUNTIME、会话 agentHarnessId/agentRuntimeOverride 状态、agents.defaults.agentRuntime 和 agents.list[].agentRuntime。运行 openclaw doctor --fix 可移除过时的整个智能体级别运行时配置，并在可以保留原始意图时转换旧版运行时模型引用。

明确指定的提供商/模型插件运行时会采用失败关闭策略：在提供商或模型上设置 agentRuntime.id: "codex" 表示必须使用 Codex，否则返回清晰的选择/运行时错误——绝不会静默路由回 OpenClaw。只有 auto 可以将未匹配的轮次路由到 OpenClaw。

CLI 后端别名不同于嵌入式 harness ID。推荐的 Claude CLI 形式：

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

出于兼容性考虑，仍支持 claude-cli/claude-opus-4-7 等旧版引用，但新配置应保持提供商/模型的规范形式，并将执行后端放入提供商/模型运行时策略中。

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

对于大多数提供商，auto 模式有意采取保守策略。OpenAI 智能体模型是例外：未设置运行时和使用 auto 都会解析到 Codex harness。对于 openai/* 智能体轮次，明确配置 OpenClaw 运行时仍是一条需主动启用的兼容性路由；当它与所选的 openai OAuth 配置文件配合使用时，OpenClaw 会通过 Codex 身份验证传输层在内部路由该路径，同时将公共模型引用保留为 openai/*。过时的 OpenAI 运行时会话固定配置会被运行时选择逻辑忽略，并可使用 openclaw doctor --fix 清理。

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

GitHub Copilot agent runtime

外部 @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" },        },      },    },  },}

该 harness 在 extensions/copilot/doctor-contract-api.ts 中声明其提供商、 运行时、CLI 会话键和身份验证配置文件前缀，openclaw doctor 会自动加载这些声明。 有关配置、身份验证、对话记录镜像、压缩、声明式 Doctor 契约，以及更广泛的 PI、Codex 与 Copilot SDK 选型决策，请参阅 GitHub Copilot agent runtime。

兼容性契约

当运行时并非 OpenClaw 时，其文档应说明它支持哪些 OpenClaw 功能面：

Codex 运行时支持契约记录于 Codex harness runtime。

状态标签

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

• openai/gpt-5.6-sol 之类的模型引用表示选中的提供商/模型。
• codex 之类的运行时 ID 表示正在执行该轮次的循环。
• Telegram 或 Discord 之类的渠道标签表示对话发生的位置。

如果某次运行显示了非预期的运行时，请先检查所选提供商/模型的运行时策略。 旧版会话运行时固定设置不再决定路由。

相关内容

• Codex harness
• Codex harness runtime
• GitHub Copilot agent runtime
• OpenAI
• Agent harness plugins
• Agent loop
• Models
• 状态