OpenClaw 快速开始:从安装到 Gateway 网关与首个渠道的五分钟上手指南
OpenClaw 快速开始:从安装到 Gateway 网关与首个渠道的五分钟上手指南
本篇指南基于 OpenClaw 官方「快速开始」(quickstart.md)展开,带你以最快路径完成「安装 CLI → 新手引导 → 配对渠道 → 启动 Gateway 网关 → 发送第一条消息」的完整闭环。读完本文,你将掌握 openclaw onboard、openclaw channels login、openclaw gateway 与 openclaw message send 四个核心命令的实战用法,并能通过 OPENCLAW_CONFIG_PATH / OPENCLAW_STATE_DIR 环境变量在单机上运行多个相互隔离的 Gateway 网关实例。
前置条件
除 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)。
相关文档
- Gateway 网关 CLI 参考(运行、查询、发现、服务管理)
- onboard 新手引导向导
- channels 渠道管理
- message 消息发送
- Gateway 网关配置(
~/.openclaw/openclaw.json全部配置项) - 入门指南(零到第一条消息)
- 设置与个性化策略
- 新手引导流程(macOS 应用)
- 源码参考:config/paths.ts(状态目录/配置路径/端口解析)、cli/gateway-cli/run.ts(Gateway 网关启动选项实现)