快速开始

目标:尽快从零到第一次正常聊天(使用合理的默认设置)。

最快的聊天方式:打开 Control UI(无需设置 Channel)。运行 openclaw dashboard 在浏览器中聊天,或在 Gateway 主机上打开 http://127.0.0.1:18789/。 文档:Dashboard 和 Control UI。

推荐路径:使用 CLI 引导向导(openclaw onboard)。它会设置:

  • 模型和认证(推荐 OAuth)
  • Gateway 设置
  • Channel(WhatsApp/Telegram/Discord/Mattermost (plugin)/…)
  • Pairing 默认值(安全的私信)
  • Workspace 初始化 + Skill
  • 可选的后台服务

如果你想查看更详细的参考页面,跳转到:向导、设置、配对、安全。

Sandbox 说明:agents.defaults.sandbox.mode: "non-main" 使用 session.mainKey(默认为 "main"),因此群组/Channel Session 会被沙箱化。如果你想让主 Agent 始终在主机上运行,设置一个明确的 Agent 覆盖配置:

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

0) 前置要求

  • Node >=22
  • pnpm(可选;如果你从源码构建则推荐)
  • 推荐: Brave Search API key 用于网页搜索。最简单的方式: 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 key。对于 Anthropic,我们推荐使用 API key;也支持 claude setup-token。
  • Provider: WhatsApp 二维码登录、Telegram/Discord bot token、Mattermost plugin token 等。
  • Daemon: 后台安装(launchd/systemd;WSL2 使用 systemd)
    • Runtime: Node(推荐;WhatsApp/Telegram 必需)。不推荐 Bun。
  • Gateway token: 向导默认会生成一个(即使在本地回环)并存储在 gateway.auth.token 中。

向导文档:向导

认证:存储位置(重要)

  • 推荐的 Anthropic 方式: 设置 API key(向导可以为服务使用存储它)。如果你想重用 Claude Code 凭证,也支持 claude setup-token。

  • OAuth 凭证(旧版导入):~/.openclaw/credentials/oauth.json

  • 认证配置文件(OAuth + API key):~/.openclaw/agents/<agentId>/agent/auth-profiles.json

无头/服务器提示:先在普通机器上完成 OAuth,然后将 oauth.json 复制到 Gateway 主机。

3) 启动 Gateway

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

openclaw gateway status

手动运行(前台):

openclaw gateway --port 18789 --verbose

Dashboard(本地回环):http://127.0.0.1:18789/ 如果配置了 token,将其粘贴到 Control UI 设置中(存储为 connect.params.auth.token)。

⚠️ Bun 警告(WhatsApp + Telegram): Bun 在这些 Channel 上有已知问题。如果你使用 WhatsApp 或 Telegram,用 Node 运行 Gateway。

3.5) 快速验证(2 分钟)

openclaw status
openclaw health
openclaw security audit --deep

4) 配对并连接你的第一个聊天界面

WhatsApp(二维码登录)

openclaw channels login

通过 WhatsApp → Settings → Linked Devices 扫描。

WhatsApp 文档:WhatsApp

Telegram / Discord / 其他

向导可以为你写入 token/配置。如果你更喜欢手动配置,从这里开始:

Telegram 私信提示: 你的第一条私信会返回一个 Pairing 代码。批准它(见下一步),否则 bot 不会响应。

5) 私信安全(Pairing 批准)

默认策略:未知的私信会获得一个短代码,消息在批准前不会被处理。 如果你的第一条私信没有回复,批准 Pairing:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

Pairing 文档:配对

从源码运行(开发)

如果你正在开发 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/key 认证 — Agent 没有认证就无法响应。

提示:openclaw status --all 是最适合粘贴的只读调试报告。 健康探测:openclaw health(或 openclaw status --deep)向运行中的 Gateway 请求健康快照。

下一步(可选,但很棒)