跳转至

运行时配置

操作员配置:启用捆绑的原生 Codex 模式,并固定 provider、model 或按代理的运行时策略,以便在缺少 harness 时失败,而不是通过内嵌运行时路由。属于 Agent harness 插件 参考的一部分。

原生 Codex harness 模式

捆绑的 codex harness 是内嵌 OpenClaw 代理回合的原生 Codex 模式。首先启用捆绑的 codex 插件;如果您的配置使用受限允许列表,请在 plugins.allow 中包含 codex。原生应用服务器配置应使用 openai/gpt-*;OpenAI 代理回合仅在有效路由声明 Codex 兼容性时才选择 Codex harness。遗留的 Codex 模型引用应使用 openclaw doctor --fix 修复,遗留的 codex/* 模型引用仍作为原生 harness 的兼容性别名。

当此模式运行时,Codex 拥有原生线程 ID、恢复行为、压缩和应用服务器执行。OpenClaw 仍然拥有聊天频道、可见转录镜像、工具策略、审批、媒体投递和会话选择。使用 provider/model agentRuntime.id: "codex" 来要求已注册的 Codex harness。不支持的路径/认证会失败关闭(fail closed),除非 harness 在执行前声明了精确请求回退。Codex 运行时失败不会通过另一个运行时重试。

Agents API 环境

agentsapi 插件接受 plugins.entries.agentsapi.config.environment,其值为 openai_hosted 和 self_hosted。省略配置时使用 openai_hosted。

对于 self_hosted,OpenClaw 会将其准备好的绝对工作区路径作为 Agents API 的 workspace_directory 发送。执行器必须已经在该路径上拥有此目录。在选择此模式之前,请为 Gateway 的会话配置一个由操作员拥有的 webhook 控制器。控制器通过经认证的 Agents API 检索每个会话的环境 ID 和远程 URL,并按照官方自托管设置连接其执行器。它负责启动、重连和清理。OpenClaw 不会通过此设置启动或配置执行器。输入提交有 60 秒的 HTTP 截止时间,包括等待执行器连接的任何时间。控制器必须及时连接;API 更长的连接窗口不会延长此截止时间。

将 plugins.entries.agentsapi.config.hostExecutorSkillDirectories 设置为执行器主机上的绝对路径。这些目录必须已经包含技能文件,并通过执行器对 Agents API harness 可用。OpenClaw 将这些路径作为 Agents API 的 capability_directories 字段发送。harness 通过该执行器发现并读取技能;OpenClaw 不会复制或安装这些文件。此显式目录选择使用原生技能发现,不经过 OpenClaw 的逐技能资格过滤器。Gateway 函数策略仍然适用。省略和空列表保持现有行为。托管会话会忽略此列表。

更改环境或自托管工作区或技能目录后,请重置 OpenClaw 会话。现有托管会话在省略或显式 openai_hosted 配置下继续运行。此选择不会扩展 MVP 现有的工具或媒体能力。

Agents API HTTP MCP 服务器

Agents API harness 从 mcp.servers 和插件 MCP 捆绑包中读取已启用的 HTTP 服务器。在每个服务器上设置 transport: "streamable-http"、url 和可选的 headers。HTTP 连接从会话的执行环境建立,包括用于私有网络服务的自托管执行器。原生 MCP 负责发现和执行;OpenClaw 不会为这些工具创建另一个 Gateway 传输。

精确的 toolFilter.include 名称将作为原生允许列表转发。排除项和会话工具拒绝需要显式的包含列表,并从中扣除。不支持通配符、Gateway 管理的 OAuth、遗留 SSE 和自定义 TLS 设置。不支持的服务器以及无法解析其 headers 的服务器将被省略并记录错误日志,而受支持的服务器仍保持可用。这包括请求者范围的连接和仅 URL 的定义,它们保留遗留的 SSE 默认值。更改有效的 MCP 配置或凭据需要重置会话。

Stdio MCP 转发仍是一个延后实现的缺口。添加支持后,执行器的原生 MCP 生命周期将拥有这些进程。

harness 作者可以复用 openclaw/plugin-sdk/agent-harness-runtime 中的 loadAgentHarnessMcpConfig,将启用的捆绑包和操作员定义与会话服务器覆盖项合并。它返回静态连接配置、诊断信息以及被省略的请求者范围服务器的名称,而不会打开连接。同一个 SDK 导出 decodeHeaderEnvPlaceholder,用于识别 ${NAME} 和 Bearer ${NAME} 头引用;harness 为其自身传输解析该值。读取返回服务器的 transport 字段。Doctor 会规范化操作员配置,且捆绑包加载会在这一边界之前转换外部 type 字段。传输支持以及没有 transport 的服务器默认值仍由 harness 负责。

运行时严格性

默认情况下,OpenClaw 使用 auto provider/model 运行时策略:已注册的插件 harness 可以声明兼容的有效路由,当没有匹配时由内嵌运行时处理该回合。仅有 provider/model 前缀永远不会选择 harness。当缺少 harness 选择时应失败而不是通过内嵌运行时路由时,请使用显式的 provider/model 插件运行时,例如 agentRuntime.id: "codex"。显式选择不会使不兼容的路由变得兼容。所选插件 harness 的失败始终是硬失败。这不会阻止显式的 provider/model agentRuntime.id: "openclaw"。

要为内嵌运行请求 Codex:

{
  "models": {
    "providers": {
      "openai": {
        "agentRuntime": {
          "id": "codex"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "openai/gpt-6-astra"
    }
  }
}

如果你希望为某个规范模型配置 CLI 后端,请将运行时配置放在该模型条目上:

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

代理级覆盖使用相同的模型作用域结构:

{
  "agents": {
    "entries": {
      "codex-only": {
        "model": "openai/gpt-6-astra",
        "models": {
          "openai/gpt-6-astra": {
            "agentRuntime": { "id": "codex" }
          }
        }
      }
    }
  }
}

此类旧版整体代理运行时示例将被忽略:

json validate=false { "agents": { "defaults": { "agentRuntime": { "id": "codex" } } } }

在显式插件运行时下,如果请求的执行框架未注册,或者它拒绝已解析的 provider/model 且未声明回退,会话会提前失败。即使存在显式运行时,自定义传输覆盖项也可能通过该回退选择 OpenClaw。要证明原生执行,请检查已完成结果中的实际执行框架;仅凭配置意图不足以作为证明。

此设置仅控制嵌入式代理执行框架。它不会禁用图像、视频、音乐、TTS、PDF 或其他特定于提供商的模型路由。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw