快速开始

目标：尽可能快速地从零 → 第一个可工作的聊天（使用合理的默认设置）。

最快聊天方式：打开控制界面（无需频道设置）。运行 openclaw dashboard 并在浏览器中聊天，或在网关主机上打开 http://127.0.0.1:18789/。 文档：仪表板 和 控制界面。

推荐路径：使用CLI入门向导（openclaw onboard）。它会设置：

• 模型/认证（推荐OAuth）
• 网关设置
• 频道（WhatsApp/Telegram/Discord/Mattermost（插件）/...）
• 配对默认设置（安全的私信）
• 工作空间引导 + 技能
• 可选的后台服务

如果您想要更深入的参考页面，请跳转到：向导、设置、配对、安全。

沙盒说明：agents.defaults.sandbox.mode: "non-main" 使用 session.mainKey（默认 "main"）， 因此群组/频道会话会被沙盒化。如果您希望主代理始终 在主机上运行，请设置显式的每个代理覆盖：

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/clawd",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

0) 先决条件

• Node >=22
• pnpm（可选；如果从源代码构建则推荐）
• 推荐： Brave搜索API密钥用于网络搜索。最简单路径： openclaw configure --section web（存储 tools.web.search.apiKey）。 参见网络工具。

macOS：如果您计划构建应用程序，请安装Xcode / CLT。仅用于CLI + 网关，Node就足够了。 Windows：使用WSL2（推荐Ubuntu）。强烈推荐WSL2；原生Windows未经测试，问题更多，工具兼容性较差。首先安装WSL2，然后在WSL内运行Linux步骤。参见Windows (WSL2)。

1) 安装CLI（推荐）

curl -fsSL https://openclaw.ai/install.sh | bash

安装程序选项（安装方法、非交互式、从GitHub）：安装。

Windows（PowerShell）：

iwr -useb https://openclaw.ai/install.ps1 | iex

替代方案（全局安装）：

npm install -g openclaw@latest

pnpm add -g openclaw@latest

2) 运行入门向导（并安装服务）

openclaw onboard --install-daemon

您将选择：

• 本地 vs 远程 网关
• 认证：OpenAI Code（Codex）订阅（OAuth）或API密钥。对于Anthropic，我们推荐API密钥；也支持 claude setup-token。
• 提供商：WhatsApp二维码登录、Telegram/Discord机器人令牌、Mattermost插件令牌等。
• 守护进程：后台安装（launchd/systemd；WSL2使用systemd）
  • 运行时：Node（推荐；WhatsApp/Telegram必需）。Bun不推荐。
• 网关令牌：向导默认生成一个（即使在回环地址上）并存储在 gateway.auth.token 中。

向导文档：向导

认证：存储位置（重要）

• 推荐的Anthropic路径： 设置API密钥（向导可以存储以供服务使用）。如果您想重用Claude Code凭据，也支持 claude setup-token。

• OAuth凭据（旧版导入）：~/.clawdbot/credentials/oauth.json

• 认证配置文件（OAuth + API密钥）：~/.clawdbot/agents/<agentId>/agent/auth-profiles.json

无头/服务器提示：首先在普通机器上进行OAuth，然后将 oauth.json 复制到网关主机。

3) 启动网关

如果您在入门期间安装了服务，网关应该已经在运行：

openclaw gateway status

手动运行（前台）：

openclaw gateway --port 18789 --verbose

仪表板（本地回环）：http://127.0.0.1:18789/ 如果配置了令牌，请将其粘贴到控制界面设置中（存储为 connect.params.auth.token）。

⚠️ Bun警告（WhatsApp + Telegram）： Bun与这些频道存在已知问题。 如果您使用WhatsApp或Telegram，请使用Node运行网关。

3.5) 快速验证（2分钟）

openclaw status
openclaw health
openclaw security audit --deep

4) 配对 + 连接您的第一个聊天界面

WhatsApp（二维码登录）

openclaw channels login

通过WhatsApp → 设置 → 已连接的设备进行扫描。

WhatsApp文档：WhatsApp

Telegram / Discord / 其他

向导可以为您写入令牌/配置。如果您更喜欢手动配置，请从以下开始：

• Telegram：Telegram
• Discord：Discord
• Mattermost（插件）：Mattermost

Telegram私信提示： 您的第一条私信会返回一个配对码。批准它（参见下一步），否则机器人不会响应。

5) 私信安全（配对批准）

默认策略：未知私信会收到一个短代码，消息在批准前不会被处理。 如果您的第一条私信没有回复，请批准配对：

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

配对文档：配对

从源代码（开发）

如果您正在修改openclaw本身，请从源代码运行：

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

如果您还没有全局安装，请通过 pnpm openclaw ... 从仓库运行入门步骤。 pnpm build 也会打包A2UI资源；如果您只需要运行该步骤，请使用 pnpm canvas:a2ui:bundle。

网关（从此仓库）：

node openclaw.mjs gateway --port 18789 --verbose

7) 端到端验证

在新终端中，发送测试消息：

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

如果 openclaw health 显示"no auth configured"，请返回向导并设置OAuth/密钥认证 — 否则代理将无法响应。

提示：openclaw status --all 是最好的可粘贴、只读调试报告。 健康检查：openclaw health（或 openclaw status --deep）向运行的网关请求健康快照。

下一步（可选，但很棒）

• macOS菜单栏应用 + 语音唤醒：macOS应用
• iOS/Android节点（画布/摄像头/语音）：节点
• 远程访问（SSH隧道 / Tailscale Serve）：远程访问 和 Tailscale
• 始终在线 / VPN设置：远程访问、exe.dev、Hetzner、macOS远程