Agent Runtimes

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

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

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

运行时分为两类：

• 嵌入式执行框架在 OpenClaw 已准备好的智能体循环内运行：包括 内置 openclaw 运行时，以及已注册的插件执行框架，例如 codex 和 copilot。
• CLI 后端运行本地 CLI 进程，同时保持模型引用 规范。例如，anthropic/claude-opus-5 搭配模型范围的 agentRuntime.id: "claude-cli" 表示“选择 Anthropic 模型，通过 Claude CLI 执行”。claude-cli 不是嵌入式执行框架 ID，不得 传递给 AgentHarness 选择逻辑。

copilot 执行框架是一个独立、需显式启用的外部插件执行框架，用于 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 和类似的外部 执行框架仍使用 ACP。

决策树：

1. Codex 绑定/控制/线程/恢复/引导/停止 -> 启用内置 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 或其他外部执行框架 -> 使用 ACP/acpx，而不是原生子智能体运行时。

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

运行时所有权

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

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

运行时选择

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。

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

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

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 等旧版引用仍受支持， 但新配置应保持提供商/模型引用规范，并将 执行后端放入提供商/模型运行时策略中。

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

对于大多数提供商，auto 模式有意采取保守策略。OpenAI 智能体 模型属于例外：未设置运行时和 auto 都会解析为 Codex 执行框架。显式 OpenClaw 运行时配置仍是 openai/* 智能体轮次的 可选兼容路由；当它与所选的 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
• 状态