Skip to main content
一个智能体运行时拥有一个准备好的模型循环：它接收提示词， 驱动模型输出，处理原生工具调用，并将完成的轮次返回给 OpenClaw。 运行时很容易与提供商混淆，因为两者都会出现在模型 配置附近。它们属于不同层：
层级示例含义
提供商anthropic, github-copilot, openaiOpenClaw 如何认证、发现模型以及命名模型引用。
模型claude-opus-4-6, gpt-5.5为智能体轮次选择的模型。
智能体运行时claude-cli, codex, copilot, openclaw执行已准备轮次的底层循环或后端。
渠道Discord, Slack, Telegram, WhatsApp消息进入和离开 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 名称：
接口面OpenClaw 名称/配置作用
Native Codex app-server 运行时openai/* 模型引用通过 Codex app-server 运行 OpenAI 嵌入式智能体轮次。这是常见的 ChatGPT/Codex 订阅设置。
Codex OAuth 认证配置文件openai OAuth 配置文件存储 Codex app-server harness 使用的 ChatGPT/Codex 订阅认证。
Codex ACP 适配器runtime: "acp", agentId: "codex"通过外部 ACP/acpx 控制平面运行 Codex。仅在明确要求 ACP/acpx 时使用。
Native Codex 聊天控制命令集/codex ...从聊天中绑定、恢复、Steer、停止和检查 Codex app-server 线程。
面向非智能体接口面的 OpenAI Platform API 路由openai/* 加 API key 认证直接 OpenAI API，例如图像、嵌入、语音和实时。
这些接口面有意保持独立。启用 codex 插件会让原生 app-server 功能可用；openclaw doctor --fix 负责旧版 Codex 路由修复和过期会话固定项清理。现在为智能体模型选择 openai/* 表示“通过 Codex 运行它”，除非正在使用非智能体的 OpenAI API 接口面。 常见的 ChatGPT/Codex 订阅设置使用 Codex OAuth 进行认证，但 将模型引用保持为 openai/*，并选择 codex 运行时： 
{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
    },
  },
}
这表示 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。 决策树：
  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>；当旧模型引用隐含该意图时，Doctor 会通过添加提供商/模型作用域的 agentRuntime.id: "codex" 来保留 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，而不是原生子智能体运行时。
你的意思是…使用…
Codex app-server 聊天/线程控制来自内置 codex 插件的 /codex ...
Codex app-server 嵌入式智能体运行时openai/* 智能体模型引用
OpenAI Codex OAuthopenai OAuth 配置文件
Claude Code 或其他外部 harnessACP/acpx
关于 OpenAI 系列前缀拆分，请参阅 OpenAI 和 模型提供商。关于 Codex 运行时支持 契约，请参阅 Codex harness runtime。

​
运行时所有权

不同运行时拥有循环中的不同部分：
接口面OpenClaw 嵌入式Codex app-server
模型循环所有者OpenClaw，通过 OpenClaw 嵌入式运行器Codex app-server
规范线程状态OpenClaw 转录Codex 线程，加 OpenClaw 转录镜像
OpenClaw 动态工具原生 OpenClaw 工具循环通过 Codex 适配器桥接
原生 shell 和文件工具OpenClaw 路径Codex 原生工具，在支持处通过原生钩子桥接
上下文引擎原生 OpenClaw 上下文组装OpenClaw 将组装好的上下文投射到 Codex 轮次中
压缩OpenClaw 或选定的上下文引擎Codex 原生压缩，配合 OpenClaw 通知和镜像维护
渠道投递OpenClawOpenClaw
设计规则：如果 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。显式 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 vs Codex vs Copilot SDK 决策，请参阅 GitHub Copilot agent runtime。

​
兼容性契约

当运行时不是 OpenClaw 时，其文档应说明它支持哪些 OpenClaw 表面：
问题重要原因
谁拥有模型循环？决定重试、工具继续执行和最终回答决策发生在哪里。
谁拥有规范线程历史？决定 OpenClaw 能否编辑历史，还是只能镜像历史。
OpenClaw 动态工具能否工作？消息、会话、cron 和 OpenClaw 拥有的工具依赖此能力。
动态工具钩子能否工作？插件期望在 OpenClaw 拥有的工具周围使用 before_tool_call、after_tool_call 和中间件。
原生工具钩子能否工作？shell、patch 和运行时拥有的工具需要原生钩子支持来实现策略和观察。
上下文引擎生命周期是否运行？记忆和上下文插件依赖 assemble、ingest、after-turn 和压缩生命周期。
暴露了哪些压缩数据？有些插件只需要通知；其他插件需要保留/丢弃的元数据。
哪些内容是有意不支持的？用户不应在原生运行时拥有更多状态的地方假设它与 OpenClaw 等价。
Codex 运行时支持契约记录在 Codex harness runtime 中。

​
状态标签

状态输出可以同时显示 Execution 和 Runtime 标签。请将它们视为诊断信息，而不是提供商名称：
  • 像 openai/gpt-5.5 这样的模型引用是选中的提供商/模型。
  • 像 codex 这样的运行时 ID 是执行该轮次的循环。
  • 像 Telegram 或 Discord 这样的渠道标签表示对话发生的位置。
如果某次运行显示了意外的运行时，请先检查所选提供商/模型的运行时策略。旧版会话运行时固定项不再决定路由。

​
相关内容