openclaw-easy-tutorial-zh-cn

Gateway 是啥？怎么用 API 和别的系统对接？

读完这一节，你会把 Gateway 在整条链路里的角色想清楚，知道怎么在本机或远程打开控制台、怎么用 HTTP API 让别的程序调用你的助手，以及远程访问时的大致做法（SSH 隧道、Tailscale）。适合已经日常在用 OpenClaw、想和自建系统或脚本对接的你。

Gateway 在整条链路里干啥

前面我们把 Gateway 比作「桥」：飞书、Telegram、WhatsApp 发来的消息先到它，再由它转给助手；助手的回复也经它发回对应渠道。更准确一点说：

你用自己的程序或脚本和 OpenClaw「对接」，本质上就是：和这台 Gateway 对话——要么用网页（Control UI），要么用 HTTP API 或 WebSocket 协议。

控制台与远程访问

Control UI（控制台）是 Gateway 自带的网页界面：聊天、看会话、改配置等。它和 Gateway 在同一个端口上，本机访问就是：

第一次从本机浏览器连，一般会自动通过；从别的电脑连（例如你在公司想访问家里的 Gateway），就需要「能访问到那台机器」且做设备配对（在运行 Gateway 的机器上执行 openclaw devices list、openclaw devices approve <requestId>）。
要安全地「从外面」访问，通常有两种方式：

  1. SSH 隧道
    在你当前电脑上执行：
    ssh -N -L 18789:127.0.0.1:18789 用户@运行Gateway的机器
    这样本机的 18789 会转发到那台机器的 18789；然后你在本机浏览器打开 http://127.0.0.1:18789/，实际连的就是远程的 Gateway。隧道保持期间，用起来和本地一样。

  2. Tailscale 等 VPN / 内网
    若运行 Gateway 的机器和你的电脑都在同一 Tailscale 网络里，可以用 Tailscale 的地址直接访问（例如 http://那台机器的 tailscale 名:18789）。Gateway 还可配合 Tailscale Serve 暴露控制台，详见官方 Remote access、Tailscale。

安全提醒：不要把 Gateway 端口直接暴露到公网。用隧道或 Tailscale 等限制在可信网络内；若必须对外，务必配好认证（token/密码）并理解下面 API 的「全权限」性质。

用 HTTP API 和别的系统对接

Gateway 提供一个 OpenAI 兼容的 HTTP 接口，方便你自己的程序、脚本或第三方工具（如支持 OpenAI 兼容接口的客户端）直接发请求、拿助手回复。这样就能实现「别的系统调你的 OpenClaw 助手」。

接口是什么、在哪

请求会走和「控制台 / 渠道」同一套助手逻辑（同一套路由、权限、模型），所以行为一致。

认证

使用 Gateway 的认证方式，在请求头里带 Bearer Token：

认证失败过多时，可能返回 429（含 Retry-After），需控制重试。

安全边界（必读）

这个 HTTP 接口是全操作员权限：谁拿着合法 token/密码，谁就被视为「这台 Gateway 的信任操作者」。

在配置里打开接口

在 ~/.openclaw/openclaw.json 里加上：

{
  gateway: {
    http: {
      endpoints: {
        chatCompletions: { enabled: true },
      },
    },
  },
}

保存后若未自动生效，执行 openclaw gateway restart。

选哪个助手（多 Agent 时）

若你配了多个 Agent，可以在请求里指定用哪一个：

高级用法还可用 x-openclaw-session-key 指定会话，详见官方 OpenAI Chat Completions。

简单示例（curl）

不流式：

curl -sS http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer 你的GatewayToken' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "messages": [{"role":"user","content":"你好"}]
  }'

流式（SSE）：在请求体里加 "stream": true，用 curl -N 接收事件流。详见官方文档示例。

用 CLI 发消息到渠道（脚本/自动化）

若你只是想「从脚本里往飞书/Telegram/WhatsApp 发一条消息」（由助手回复或仅发送），可以用 CLI，无需自己调 HTTP：

openclaw message send --channel telegram --target @某个用户 --message "需要提醒的内容"

--channel 填 telegram、whatsapp、feishu 等；--target 格式因渠道而异（见官方 message）。这样可以在 cron、CI 或自己的脚本里调用，实现简单自动化。更复杂的自动化（如 webhook、定时任务）可看官方 Automation、Webhooks 等文档。

本节要点

常见问题

Q：开了 chatCompletions 但请求 404？
确认配置里 gateway.http.endpoints.chatCompletions.enabled 为 true 且已生效（改配置后若未热加载，需 openclaw gateway restart）；请求 URL 是否为 http://<host>:<port>/v1/chat/completions（端口与 Gateway 一致）。

Q：返回 401 / 403？
检查请求头是否带 Authorization: Bearer <token>，且 token 与当前 Gateway 的 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）一致；若 Gateway 用的是 password 模式，则用密码而非 token。

Q：从外网如何安全访问家里的 Gateway？
不要直接把 18789 映射到公网。推荐：本机用 SSH 隧道连回家中机器，或家中机器与常用电脑都装 Tailscale，用 Tailscale 地址访问；若需对外提供控制台，用 Tailscale Serve 等限定在可信网络。详见 Remote access。

Q：API 和 Control UI 用的是同一套助手吗？
是。请求都走同一套 Gateway 逻辑，同一模型、同一工作区、同一套权限；只是入口不同（网页 vs HTTP）。

延伸阅读

← 返回目录