OpenClaw 快速开始:从安装到 Gateway 网关与首个渠道的五分钟上手指南

原创2026-10-16 10:23:101,375 阅读
文章标签:人工智能大模型AI 应用后端LLM 网关即时通讯AI Agent插件系统本地部署MCP Clients

OpenClaw 快速开始:从安装到 Gateway 网关与首个渠道的五分钟上手指南

本篇指南基于 OpenClaw 官方「快速开始」(quickstart.md)展开,带你以最快路径完成「安装 CLI → 新手引导 → 配对渠道 → 启动 Gateway 网关 → 发送第一条消息」的完整闭环。读完本文,你将掌握 openclaw onboard、openclaw channels login、openclaw gateway 与 openclaw message send 四个核心命令的实战用法,并能通过 OPENCLAW_CONFIG_PATH / OPENCLAW_STATE_DIR 环境变量在单机上运行多个相互隔离的 Gateway 网关实例。


前置条件

OpenClaw 需要 **Node 22 或更新版本**。

除 Node 之外,官方入门指南(getting-started.md)还建议准备:

  • pnpm(可选):如果计划从源码构建则推荐使用;
  • 网页搜索 API 密钥(可选):推荐配置 Brave Search,最简单的方式是运行 openclaw configure --section web;
  • macOS:仅使用 CLI + Gateway 网关时 Node 即可,无需 Xcode;
  • Windows:强烈推荐先安装 WSL2(建议 Ubuntu),然后在 WSL 内执行 Linux 步骤——原生 Windows 未经充分测试,工具兼容性较差。

关于运行时还有一个重要提醒:新手引导中可选的守护进程运行时,Node 为推荐项,Bun 不推荐,且 Bun 与 WhatsApp/Telegram 渠道存在已知问题,使用这两个渠道时请务必以 Node 运行 Gateway 网关。

安装 CLI

OpenClaw 提供 npm 与 pnpm 两种全局安装方式:

npm install -g openclaw@latest
pnpm add -g openclaw@latest

安装成功后,openclaw 命令即进入 PATH。若希望验证安装完整性,可随时运行 openclaw doctor 做健康检查与引导式修复(详见后文「故障排查」小节)。

新手引导并运行 Gateway 网关

安装完成后,官方推荐按以下三步顺序操作:

1. 新手引导并安装服务

openclaw onboard --install-daemon

openclaw onboard 是交互式新手引导向导(本地或远程 Gateway 网关设置)。根据 CLI 参考(onboard.md),它支持多种流程:

openclaw onboard                    # 默认交互式向导
openclaw onboard --flow quickstart  # 最少提示,自动生成 Gateway 网关令牌
openclaw onboard --flow manual      # 完整端口/绑定/认证提示
openclaw onboard --mode remote --remote-url ws://gateway-host:18789

向导会引导你依次决定:

  • 本地 vs 远程:Gateway 网关运行在本机还是远端主机(远程模式下凭证必须已存在于网关主机上);
  • 认证方式:OpenAI Code (Codex) 订阅 OAuth 或 API 密钥;Anthropic 推荐 API 密钥,也支持 claude setup-token;
  • 渠道提供商:WhatsApp QR 登录、Telegram/Discord 机器人令牌、Mattermost 插件令牌等;
  • 守护进程:是否后台安装服务(macOS 用 launchd,Linux 用 systemd,WSL2 使用 systemd)及运行时选择(推荐 Node);
  • Gateway 网关令牌:向导默认生成一个(即使仅在 loopback 上),并写入配置的 gateway.auth.token。

--install-daemon 的作用是把 Gateway 网关注册为后台服务。完成新手引导后,Gateway 网关将通过用户服务运行;你随时也可以改用 openclaw gateway 手动前台启动。

2. 配对 WhatsApp

openclaw channels login

openclaw channels login 是「添加/登录渠道账户」的交互式入口(channels.md)。不带参数时它会列出可用渠道并引导你登录,也可以显式指定渠道:

openclaw channels login --channel whatsapp
openclaw channels logout --channel whatsapp

以 WhatsApp 为例,登录后通过「WhatsApp → 设置 → 链接设备」扫码即可完成配对。对于 Telegram/Discord 等需要机器人令牌的渠道,向导可以直接替你写入令牌配置;手动添加账户的等价命令为:

openclaw channels add --channel telegram --token <bot-token>
openclaw channels remove --channel telegram --delete

私信配对安全提示:OpenClaw 的默认姿态是「未知私信先发配对码,批准后才处理」。如果你向机器人发送第一条私信后没有收到回复,多半是配对尚未批准,需要手动批准:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

3. 启动 Gateway 网关

openclaw gateway --port 18789

Gateway 网关是 OpenClaw 的 WebSocket 服务器,承载渠道、节点、会话与 hooks(gateway.md)。18789 是默认端口——该值在源码中被定义为 DEFAULT_GATEWAY_PORT(见 config/paths.ts),resolveGatewayPort 会依次读取 OPENCLAW_GATEWAY_PORT 环境变量、配置 gateway.port,最后回落到 18789。

启动前有两个安全护栏需要了解:

  • 必须显式配置为本地模式:默认情况下,除非在 ~/.openclaw/openclaw.json 中设置了 gateway.mode=local,否则 Gateway 网关会拒绝启动;新手引导会自动完成该配置。临时/开发运行可加 --allow-unconfigured 绕过;
  • loopback 之外必须带认证:在没有令牌/密码认证的情况下绑定到 loopback 之外的地址会被阻止(安全护栏)。实现上,cli/gateway-cli/run.ts 会检查「非 loopback 绑定 + 无共享密钥」的组合并直接报错退出。

openclaw gateway 前台运行还有一个别名:openclaw gateway run。

Gateway 网关常用启动选项

选项 说明
--port <port> WebSocket 端口(默认来自配置/环境变量,通常为 18789)
--bind <loopback|lan|tailnet|auto|custom> 监听器绑定模式
--auth <token|password> 认证模式覆盖(源码中还支持 none、trusted-proxy)
--token <token> 令牌覆盖(同时为进程设置 OPENCLAW_GATEWAY_TOKEN)
--password <password> 密码覆盖(同时设置 OPENCLAW_GATEWAY_PASSWORD);源码提示 --password 可能被进程列表暴露,优先用 --password-file 或环境变量
--tailscale <off|serve|funnel> 通过 Tailscale 暴露 Gateway 网关
--allow-unconfigured 允许在未配置 gateway.mode=local 时启动
--force 启动前强制结束目标端口上的现有监听器
--dev 缺失时创建开发配置 + 工作区(跳过 BOOTSTRAP.md)
--reset 重置开发配置 + 凭证 + 会话 + 工作区(需与 --dev 搭配)
--ws-log <auto|full|compact> WebSocket 日志样式(默认 auto),--compact 是其别名
--verbose 详细日志

服务生命周期与状态管理

如果在新手引导期间安装了后台服务,Gateway 网关应该已经在运行,可通过以下命令查看与管理:

openclaw gateway status        # 服务状态 + 可选的 RPC 探测
openclaw gateway install       # 安装服务(支持 --port/--runtime/--token/--force/--json)
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

健康与完整性检查:

openclaw health                # 从运行中的 Gateway 网关获取健康状态(--json/--verbose)
openclaw status --all          # 最全面的可粘贴只读调试报告
openclaw security audit --deep # 安全审计

提示:之后在 npm 安装与 git 安装之间切换非常简单——安装另一种方式后,运行 openclaw doctor 即可更新 Gateway 网关服务入口点。

发送测试消息

发送测试消息需要一个正在运行的 Gateway 网关。在新终端中执行:

openclaw message send --target +15555550123 --message "Hello from OpenClaw"

openclaw message 是用于发送消息与渠道操作的单一出站命令(message.md),支持 WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost(插件)/Signal/iMessage/MS Teams。

  • 渠道选择:配置了多个渠道时必须指定 --channel;只配置了一个渠道时该渠道即为默认值;
  • --target 目标格式随渠道而异:WhatsApp 使用 E.164 号码或群组 JID;Telegram 使用聊天 ID 或 @username;Discord 使用 channel:<id> 或 user:<id>;Slack 使用 channel:<id> 或 user:<id>;Signal 使用 +E.164 或 signal:group:<id>;MS Teams 使用会话 ID(19:...@thread.tacv2)或 conversation:<id>;
  • 名称解析:对于 Discord/Slack 等提供商,#general 之类的频道名会通过目录缓存解析,缓存未命中时会尝试实时目录查找;
  • 通用标志:--channel、--account、--target、--json、--dry-run、--verbose。

send 之外,openclaw message 还支持 poll、react、read、edit、delete、pin/unpin、broadcast 以及 Discord 的线程、表情、贴纸、角色管理等操作。例如创建 Discord 投票:

openclaw message poll --channel discord \
  --target channel:123 \
  --poll-question "Snack?" \
  --poll-option Pizza --poll-option Sushi \
  --poll-multi --poll-duration-hours 48

如果 openclaw health 显示「未配置认证」,请回到新手引导向导配置 OAuth 或 API 密钥——没有认证,智能体将无法响应。

从源码安装(开发)

如果你正在开发 OpenClaw 本身,或希望运行最新代码,可以从源码安装:

git clone https://gitcode.com/gh_mirrors/op/openclaw-zero-token.git openclaw
cd openclaw
pnpm install
pnpm ui:build # 首次运行时会自动安装 UI 依赖
pnpm build
openclaw onboard --install-daemon

注意事项:

  • 如果你还没有全局安装,可以在仓库目录中通过 pnpm openclaw ... 运行新手引导步骤(例如 pnpm openclaw onboard --install-daemon);
  • pnpm build 会一并打包 A2UI 资源;如果只需运行那一步,可改用 pnpm canvas:a2ui:bundle;
  • 从仓库直接运行 Gateway 网关:
node openclaw.mjs gateway --port 18789 --verbose

关于「保持个性化设置不丢失」,setup.md 给出了明确的策略:个性化内容存放在仓库之外——配置在 ~/.openclaw/openclaw.json(JSON/JSON5 格式,支持注释与尾逗号),工作区(Skills、提示、记忆)在 ~/.openclaw/workspace(建议设为私有 git 仓库)。更新源码时 git pull + pnpm install 即可,个人提示与配置不要放进 openclaw 仓库。首次个性化引导可运行 openclaw setup。

多实例快速开始(可选)

OpenClaw 支持通过两个环境变量在单机运行多个相互隔离的实例——一个独立的配置文件加一个独立的状态目录:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

从源码看(config/paths.ts),其解析逻辑非常明确:

  • OPENCLAW_STATE_DIR:状态目录,存放会话、日志、缓存等可变数据;未设置时默认 ~/.openclaw(并兼容历史上拼写为 .clawdbot / .moldbot 的旧目录);
  • OPENCLAW_CONFIG_PATH:配置文件路径(JSON/JSON5);未设置时默认取 $OPENCLAW_STATE_DIR/openclaw.json;
  • 两者均支持 ~ 相对路径展开;
  • 端口解析则遵循 OPENCLAW_GATEWAY_PORT → 配置 gateway.port → 默认 18789 的优先级。

这套机制非常适合「救援机器人」、隔离测试环境或多租户场景——配合 --port 指定不同端口,多实例之间互不干扰(注意:gateway.mode=local 仍需在每个实例的独立配置中设置,或使用 --allow-unconfigured)。

故障排查

1. openclaw doctor:健康检查 + 引导式修复

遇到连接/认证问题时,openclaw doctor 是第一工具(doctor.md):

openclaw doctor
openclaw doctor --repair   # 别名 --fix;会将备份写入 ~/.openclaw/openclaw.json.bak,并删除未知配置键
openclaw doctor --deep

交互式提示(如钥匙串/OAuth 修复)仅在 stdin 为 TTY 且未设置 --non-interactive 时运行;无头环境(cron、Telegram、无终端)会自动跳过提示。

2. Gateway 拒绝启动

  • 「Gateway start blocked」:配置缺少 gateway.mode=local。运行 openclaw setup(或 openclaw onboard)完成配置,或临时加 --allow-unconfigured;
  • 配置校验失败:OpenClaw 采用严格配置验证,未知键、类型错误或无效值会导致 Gateway 网关拒绝启动以保安全。此时仅诊断类命令可用(openclaw doctor、openclaw logs、openclaw health、openclaw status),运行 openclaw doctor 查看具体问题,openclaw doctor --fix(或 --yes)应用迁移/修复;
  • macOS launchctl 环境变量覆盖:如果之前执行过 launchctl setenv OPENCLAW_GATEWAY_TOKEN ...(或 ...PASSWORD),该值会覆盖配置文件并导致持续「未授权」错误:
launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

3. Linux 用户服务与 lingering

Linux 安装使用 systemd 用户服务,默认在注销/空闲时停止,会终止 Gateway 网关。新手引导会尝试启用 lingering(可能提示 sudo);如果仍被关闭,手动执行:

sudo loginctl enable-linger $USER

对于常驻或多用户服务器,建议改用系统服务(无需 lingering)。

4. 渠道状态与能力排查

  • 运行 openclaw status --deep 做全面探测;
  • openclaw channels list / openclaw channels status / openclaw channels logs --channel all 查看账户与运行时状态;
  • openclaw channels capabilities --channel discord --target channel:123 探测各提供商的能力(intents/scopes)。

相关文档

登录后查看全文
openclaw-zero-token