快速开始

本文目标：帮你以最快速度完成首次配置并发送第一条消息（使用合理的默认配置）。

想快速体验？直接运行 openclaw dashboard 打开控制界面，无需配置任何频道即可在浏览器中聊天。 也可以在 Gateway 主机上访问 http://127.0.0.1:18789/。 相关文档：控制面板 和 控制界面。

推荐方式：使用 CLI 入门向导（openclaw onboard）。它会自动配置：

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

如需了解更多细节，请参阅：向导、设置、配对、安全。

沙箱说明：agents.defaults.sandbox.mode: "non-main" 使用 session.mainKey（默认 "main"）， 因此群组/频道会话会被沙箱化。如果希望主 Agent 始终在主机上运行，可以为特定 Agent 单独配置：

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/clawd",
        "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://molt.bot/install.sh | bash

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

Windows (PowerShell)：

iwr -useb https://molt.bot/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 二维码登录、Telegram/Discord 机器人令牌、Mattermost 插件令牌等。
  • 守护进程：后台服务安装（launchd/systemd；WSL2 使用 systemd）
    • 运行时：Node（推荐；WhatsApp/Telegram 必需）。不推荐 Bun。
  • Gateway 令牌：向导会自动生成一个（即使在本地回环）并存储到 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 复制到 Gateway 主机。

3) 启动 Gateway

如果在入门向导中安装了服务，Gateway 应该已经在运行了：

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 运行 Gateway。

3.5) 快速验证（2 分钟）

openclaw status
openclaw health
openclaw security audit --deep

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

WhatsApp（二维码登录）

openclaw channels login

在 WhatsApp 中扫描：设置 → 已关联的设备。

WhatsApp 文档：WhatsApp

Telegram / Discord / 其他

向导可以帮你自动写入令牌/配置。如果更喜欢手动配置，请参考：

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。

Gateway（从此仓库运行）：

node dist/entry.js gateway --port 18789 --verbose

7) 端到端验证

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

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

如果 openclaw health 显示”未配置认证”，请返回向导设置 OAuth/密钥认证 — 没有认证配置，Agent 将无法响应。

提示：openclaw status --all 是最适合粘贴分享的只读调试报告。 健康检查：openclaw health（或 openclaw status --deep）会向运行中的 Gateway 请求健康状态快照。

下一步（可选，但推荐）