传输与 OAuth

以下是已保存的 MCP 服务器定义可使用的传输形态，以及 HTTP 传输可用来进行身份验证的 OAuth 工作流。

当 Codex 拥有 MCP 连接时，显式的 connectionTimeoutMs 值控制启动过程（包括初始化和初始工具发现），requestTimeoutMs 值控制工具调用。OpenClaw 在将这些值转换为 Codex 的秒级设置时会保留毫秒精度；未设置的值保留 Codex 的默认值。supportsParallelToolCalls 提示也会被转发。Codex 还可以并行运行带有 readOnlyHint 注解的工具。

Stdio 传输¶

启动一个本地子进程，并通过 stdin/stdout 进行通信。

关闭操作可强制缓慢的锚点和中继在其控制管道、输出管道和谱系管道关闭后退出。仍然存活的锚点会通过其中继被杀死并回收。如果锚点组已不存在，宿主可以直接杀死无响应的中继。宿主随后确认实际退出和组消失。已确认的清理正常完成；后续连接会启动全新的服务器。未确认的清理仍会报告错误，其中包含缺失的关闭事实、已用时间以及任何失败的信号传递。关闭升级时，清理截止时间不会改变。

SSE / HTTP 传输¶

通过 HTTP Server-Sent Events 连接到远程 MCP 服务器。

示例：

{
  "mcp": {
    "servers": {
      "remote-tools": {
        "url": "https://mcp.example.com",
        "auth": "oauth",
        "requestTimeoutMs": 20000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

url（用户信息）和 headers 中的敏感值会在日志和状态输出中被脱敏。当看似敏感的 headers 或 env 条目包含字面值时，openclaw mcp doctor 会发出警告，以便操作员将这些值移出已提交的配置。

如果旧版 SSE 消息端点返回 HTTP 404，或有状态的 Streamable HTTP 会话过期，OpenClaw 会让该连接退役，并在下一次发现时重新连接。失败的调用会被报告而不会重放，因为工具可能在连接失败之前就已经改变了状态。

OAuth 工作流¶

OAuth 适用于声明支持 MCP OAuth 流程的 HTTP MCP 服务器。启用 auth: "oauth" 时，服务器会忽略静态的 Authorization 标头。默认情况下，OAuth 凭据是共享的，并由操作员管理。通过 openclaw mcp login 保存的凭据可用于嵌入式 MCP、CLI 运行器和本地 Codex 应用服务器。

原生 MCP OAuth 会话存储在仅所有者可访问的共享 SQLite 数据库中，路径为 <state-dir>/state/openclaw.sqlite（mcp_oauth_stores）。该行可包含访问令牌和刷新令牌、动态客户端注册密钥、发现元数据以及临时的 PKCE 验证器。刷新、登录和注销使用同一个 SQLite 租约，因此并行的 OpenClaw 进程无法消耗同一个刷新令牌，也无法复活已注销的会话。

仅由 openclaw doctor --fix 处理从已退役的 <state-dir>/mcp-oauth/*.json 存储进行的升级。运行时代码从不读取、写入或回退到这些文件。

在共享凭据可用之前，OpenClaw 只会将该 MCP 服务器从代理运行时中省略，而不是使代理回合失败。操作员或具有 shell 访问权限的代理随后可以运行 openclaw mcp login <name>，并在后续回合中使用该服务器。

如果服务器以 insufficient_scope 拒绝令牌，OpenClaw 会保留请求的 scope，并要求执行 openclaw mcp login <name>，而不是重复无法授予新 scope 的刷新。该登录会启动新的授权请求，同时保留先前令牌，直到替换凭据被保存。

当远程 MCP 服务已由另一个支持刷新的 OpenClaw 认证配置支持时，可以可选地设置 oauth.authProfileId。OpenClaw 会在运行时投影前刷新任一凭据源，并只将当前访问令牌传递给下游 MCP 客户端。

当每个已认证发送者都应连接独立账户时，设置 oauth.identity: "per-requester"。按请求者 OAuth 需要 HTTP 服务器 URL，并且不能使用 oauth.authProfileId。将 gateway.publicOrigin 配置为 Gateway 的外部可达 HTTPS 源；本地开发期间，仅对字面回环主机（localhost、127.0.0.1 或 [::1]）接受 HTTP。授权后，提供商会重定向到 <gateway.publicOrigin>/oauth/mcp/callback。

{
  gateway: {
    publicOrigin: "https://gateway.example.com",
  },
  mcp: {
    servers: {
      docs: {
        url: "https://mcp.example.com/mcp",
        transport: "streamable-http",
        auth: "oauth",
        oauth: {
          identity: "per-requester",
          scope: "docs.read",
        },
      },
    },
  },
}

按请求者流程由发送者驱动：

1. 发送者在连接账户之前调用来自该服务器的工具。
2. OpenClaw 会为该发送者返回登录链接，而不是暴露其他发送者的凭据。
3. 提供商通过 Gateway 回调进行重定向。回调成功后，发送者使用其已连接账户重试工具调用。

如果缺少 gateway.publicOrigin，登录结果会指明该设置，并且 openclaw doctor 会报告相同操作员修复。openclaw mcp login 和 openclaw mcp logout 仍然是仅限操作员命令，用于共享凭据；它们不管理按请求者账户。

登录链接是一次性 bearer 链接：任何打开该链接的聊天参与者都会将自己账户连接到该链接所针对的发送者。在可信发送者彼此互相信任的频道中使用按请求者 OAuth；请求者私有的登录交接被记录为后续工作。

共享操作员流程使用以下命令：

1. 保存服务器

使用 auth: "oauth" 和任意可选 OAuth 元数据添加或更新服务器。

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'

对于由认证配置支持的 bearer，保存配置绑定：

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"authProfileId":"docs:mcp"}}'

2. 开始登录

运行登录以创建授权请求。

openclaw mcp login docs

OpenClaw 会启动已注册的回环回调，打印授权 URL，并将临时 OAuth verifier 状态存储在共享 SQLite 中。在浏览器中批准请求并返回终端；回调到达后，令牌交换会自动完成。

3. 必要时使用手动回退

如果浏览器运行在另一台机器上，或无法访问打印的回环地址，请复制返回的代码并将其传回 OpenClaw。

openclaw mcp login docs --code abc123

4. 检查授权

使用 status 或 doctor 确认令牌存在且不需要额外授权。如果 status 报告 authorization-required，或 doctor 要求额外授权，请再次运行 openclaw mcp login <name>。

openclaw mcp status --verbose
openclaw mcp doctor docs --probe

5. 清除凭据

登出会删除已存储的 OAuth 凭据，但保留已保存的服务器定义。

openclaw mcp logout docs

如果提供商轮换令牌或授权状态卡住，请运行 openclaw mcp logout <name>，然后重复 login。即使 auth: "oauth" 已从配置中移除，只要服务器名称和 URL 仍能标识凭据存储条目，logout 就可以清除已保存 HTTP 服务器的凭据。

Streamable HTTP 传输¶

streamable-http 是与 sse 和 stdio 并列的额外传输选项。它使用 HTTP 流式传输与远程 MCP 服务器进行双向通信。

OpenClaw 配置使用 transport: "streamable-http" 作为规范拼写。CLI 原生 MCP 中 type: "http" 的值在通过 openclaw mcp set 保存时会被接受，并会在现有配置中由 openclaw doctor --fix 修复，但 transport 才是嵌入式 OpenClaw 直接使用的字段。

示例：

{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectionTimeoutMs": 10000,
        "requestTimeoutMs": 30000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}