OpenClaw 入门：一个 Gateway，管住你所有的聊天入口

Posted on Wed 07 October 2026 in AI 编程 • Sucre Liu

先纠正一个定位

如果你带着用 Claude Code、OpenCode 的经验来装 OpenClaw，很容易低估它。那两样是"你打开它、用它干活"；OpenClaw 是一个常驻网关——它自己跑着，把你的助手接到你日常在用的聊天软件里（Discord、Slack、Telegram、WhatsApp、iMessage、Teams、Matrix 等 20 多个）。

一个关键数字：一台主机只有一个 Gateway。它是唯一打开 WhatsApp 会话的地方，也是唯一持有你凭据、会话、权限的地方。理解它是"服务"而非"命令"，后面所有配置才有正确的心理模型。

本文基于 OpenClaw 2026.9.5，只讲从零到"发出第一条消息"这条最短路径，以及一开始就该建立的边界意识。

架构：谁连谁

拆开看是这样：

        你的手机 / 电脑上的聊天软件
                    │  (渠道插件)
                    ▼
   ┌──────────────────────────────┐
   │        Gateway（常驻）        │
   │  会话 / 工具 / 事件 / 渠道     │  ← WebSocket，默认 127.0.0.1:18789
   └──────────────────────────────┘
        ▲                ▲
        │                │
   控制面客户端         Nodes（macOS/iOS/Android/headless）
   (CLI / 网页 UI /     role: node，声明 caps/commands
    自动化)

几个要点：

控制面客户端（macOS 应用、CLI、网页 UI、自动化）通过 WebSocket 连到 Gateway。
Nodes 也走同一个 WS，但声明 role: node 并带上明确能力（摄像头、屏幕录制、定位等）。配对是基于设备的。
Gateway 的 HTTP 端口还挂着托管界面资源（/__openclaw__/canvas/、/__openclaw__/a2ui/），和控制面同端口（默认 18789）。
协议是文本 JSON 帧；第一帧必须是 connect，否则直接断开。

记住这条不变量：所有连接（本地或远程）都要过 gateway.auth.* 鉴权。本地 loopback 的首次配对可以自动批准，但鉴权本身不豁免。

安装与首次启动

要求 Node 24.16+ 或 26.1+（推荐 26）。两条路径：

# 官方安装脚本（macOS / Linux / WSL2）
curl -fsSL https://openclaw.ai/install.sh | bash

# 或自行管理 Node，走 npm
npm install -g openclaw@latest --allow-scripts=openclaw

（Windows PowerShell 用 iwr -useb https://openclaw.ai/install.ps1 | iex。）

最省事的试跑是：

npx openclaw@latest

新装环境下选 Quick start 就行。它的聪明之处在于：如果本机已经有可用的 Claude Code 或 Codex 登录或 API key，它会复用、用一次真实补全验证、写好配置，然后打开网页控制台。省掉一堆 provider 手工配置。

默认情况下 Gateway 就跑在这个终端里，按 Ctrl+C 才停，配置会保留。想让它常驻后台，就要装服务：

openclaw gateway install
openclaw gateway status      # 应看到监听在 18789
openclaw dashboard           # 打开 Control UI

gateway install 会按平台装成 LaunchAgent / systemd user unit / Windows 计划任务。之后在 Control UI 里发一条消息，收到回复，链接就算通了。

想用手机聊？最快接的通道是 Telegram，只需要一个 bot token。通道篇会细讲。

出问题时的正确第一步

不要一上来翻日志。OpenClaw 自带一个诊断入口：

openclaw triage

它跑只读健康检查，写出一份脱敏的诊断提示，然后询问是否交给你机器上检测到的编码代理（Claude Code、Codex 或内置 agent）继续修。在你选择代理之前，没有任何数据离开本机；密钥、token、原始聊天内容、原始日志都不会进这份提示。

愿意自己看就：

openclaw doctor

doctor 是这套系统里最该记住的命令——配置校验失败、通道不健康、插件没加载、状态需要迁移，它都能给出问题所在，openclaw doctor --fix 则尝试修复。

一开始就该建立的边界

因为是常驻服务，有两件事必须在接通道之前想清楚：

谁在给 bot 发消息？ 具备私聊能力的通道默认对陌生发件人配对（pairing）——陌生人的消息在批准前不会被处理。别图省事把它设成公开。
工具在哪跑？ 默认情况下工具在主机的主会话里直接执行，除非你配置沙箱（sandboxing 默认关闭）。如果你打算接入其他人，先读安全指南，或至少把非主会话放进沙箱。

一句话：把 OpenClaw 当成一台你对外开放了端口的服务器，而不是一个装在笔记本里的 App。这个心态会让后面每一步都更稳。

五条命令先记住

openclaw                    # 打开终端 TUI
openclaw dashboard          # 打开网页控制台
openclaw gateway status     # 看网关状态
openclaw doctor             # 体检
openclaw triage             # 出问题时的脱敏诊断 + 交给代理

小结

OpenClaw 是常驻网关：一台主机一个，管住所有聊天入口与执行。
架构三件套：Gateway（常驻）+ 控制面客户端 + Nodes，全部经 WebSocket，默认 127.0.0.1:18789。
最短路径：npx openclaw@latest → Quick start → gateway install → dashboard。
出问题先 triage / doctor，别猜。
接通道前先定两件事：谁能发消息、工具在哪跑。

下一篇讲配置：~/.openclaw/openclaw.json 的"两桶规则"、为什么一个拼错的键会让 Gateway 拒绝启动，以及 provider/model 引用怎么解析。