运行时配置

操作者配置：启用随附的原生 Codex 模式，并固定 provider、model 或按 agent 的运行时策略，以便缺少 harness 时直接失败，而不是通过嵌入式运行时路由。属于 Agent harness 插件 参考文档的一部分。

原生 Codex harness 模式¶

随附的 codex harness 是嵌入式 OpenClaw agent 回合的原生 Codex 模式。首先启用随附的 codex 插件，如果你的配置使用限制性 allowlist，请将 codex 包含在 plugins.allow 中。原生应用服务器配置应使用 openai/gpt-*；OpenAI agent 回合仅在有效路由声明 Codex 兼容性时才选择 Codex harness。旧版 Codex 模型引用应通过 openclaw doctor --fix 修复；旧版 codex/* 模型引用仍是原生 harness 的兼容别名。

当此模式运行时，Codex 负责原生 thread id、恢复行为、压缩和应用服务器执行。OpenClaw 仍负责聊天频道、可见的转录镜像、工具策略、审批、媒体投递和会话选择。使用 provider/model agentRuntime.id: "codex" 来要求已注册的 Codex harness。除非 harness 在执行前声明了 exact-request 回退，否则不支持的 route/auth 会按 fail closed 方式失败。Codex 运行时失败不会通过其他运行时进行重试。

Agents API 环境¶

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

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

将 plugins.entries.agentsapi.config.hostExecutorSkillDirectories 设置为 executor 宿主机上的绝对路径。这些目录必须已经配置好 skill 文件，并且可通过 executor 提供给 Agents API harness。OpenClaw 会将这些路径作为 Agents API 的 capability_directories 字段发送。harness 通过该 executor 发现并读取 skill；OpenClaw 不会复制或安装这些文件。

这种显式目录选择使用原生 skill 发现机制，不经过 OpenClaw 的按 skill 资格过滤器。Gateway 函数策略仍然适用。

省略或空的列表保持现有行为。托管会话（hosted sessions）会忽略此列表。

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

Agents API HTTP MCP 服务器¶

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

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

Stdio MCP 转发仍是延后实现的缺口。加入支持后，executor 的原生 MCP 生命周期将接管这些进程。

harness 作者可以复用 openclaw/plugin-sdk/agent-harness-runtime 中的 loadAgentHarnessMcpConfig，将启用的 bundle 和操作者定义与会话服务器覆盖项合并。它返回静态连接配置、诊断信息以及被省略的 requester 作用域服务器名称，而不会打开连接。同一 SDK 还导出 decodeHeaderEnvPlaceholder，用于识别 ${NAME} 和 Bearer ${NAME} 的 header 引用；harness 会为自身的 transport 解析该值。

请读取返回的服务器的 transport 字段。Doctor 会规范化操作者配置，bundle 加载会在该边界之前转换外部的 type 字段。对 transport 的支持以及未提供 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": {
        "default": true,
        "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 或其他特定提供商的模型路由。