1.2 快速开始

开始指南开始指南

目标：从零开始，尽快完成首次聊天（使用合理的默认配置）。

最快聊天方式
打开 Control UI（无需设置频道）。运行 openclaw dashboard 在浏览器中聊天，或在 Gateway 主机上打开 http://127.0.0.1:18789/。详见：Dashboard 和 Control UI。

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

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

如需更深入的参考页面，请跳转至：向导、设置、配对、安全。

沙箱说明

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

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

0) 前置条件

  • Node ≥22
  • pnpm（可选；如果从源码构建则推荐）
  • 推荐：Brave Search API 密钥用于网页搜索。最简单的方法：openclaw configure --section web（存储 tools.web.search.apiKey）。详见 Web 工具。
  • macOS：如果计划构建应用，请安装 Xcode / CLT。仅 CLI + Gateway 只需 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 远程 Gateway
  • 认证：OpenAI Code (Codex) 订阅（OAuth）或 API 密钥。对于 Anthropic，我们推荐使用 API 密钥；也支持 claude setup-token。
  • 提供商：WhatsApp QR 登录、Telegram/Discord bot tokens、Mattermost 插件 tokens 等。
  • 守护进程：后台安装（launchd/systemd；WSL2 使用 systemd）
  • 运行时：Node（推荐；WhatsApp/Telegram 必需）。不推荐使用 Bun。
  • Gateway token：向导默认生成一个（即使在 loopback 上）并存储在 gateway.auth.token 中。

向导文档：向导

认证：存储位置（重要）

  • 推荐的 Anthropic 路径：设置 API 密钥（向导可以为服务使用存储它）。如果要重用 Claude Code 凭据，也支持 claude setup-token。
  • OAuth 凭据（旧版导入）：~/.openclaw/credentials/oauth.json
  • 认证配置文件（OAuth + API 密钥）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 无头/服务器提示：先在普通机器上完成 OAuth，然后将 oauth.json 复制到 Gateway 主机。

3) 启动 Gateway

如果在引导过程中安装了服务，Gateway 应该已经在运行：

openclaw gateway status

手动运行（前台）：

openclaw gateway --port 18789 --verbose

Dashboard（本地 loopback）：http://127.0.0.1:18789/ 如果配置了 token，将其粘贴到 Control UI 设置中（存储为 connect.params.auth.token）。

Bun 警告（WhatsApp + Telegram）
Bun 在这些频道上存在已知问题。如果使用 WhatsApp 或 Telegram，请使用 Node 运行 Gateway。

3.5) 快速验证（2 分钟）

openclaw status
openclaw health
openclaw security audit --deep

4) 配对并连接你的首个聊天平台

WhatsApp（QR 登录）

openclaw channels login

通过 WhatsApp → 设置 → 已链接设备 扫描。

WhatsApp 文档：WhatsApp

Telegram / Discord / 其他

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

Telegram DM 提示：你的第一条 DM 会返回配对码。批准它（见下一步）否则 bot 不会响应。

5) DM 安全（配对审批）

默认姿态：未知的 DM 会收到一个短码，消息在批准前不会被处理。如果你的第一条 DM 没有收到回复，请批准配对：

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

配对文档：配对

6) 从源码安装（开发）

如果你正在开发 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。

Gateway（从此仓库）：

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）向运行中的 Gateway 请求健康快照。

下一步（可选，但推荐）