快速开始

目标：尽快从 零 → 首次工作对话（使用合理的默认设置）。

最快对话方式：打开控制界面（无需设置频道）。运行 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": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

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

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

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

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

Windows (PowerShell):

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

替代方案（全局安装）：

npm install -g openclaw@latest

pnpm add -g openclaw@latest

openclaw onboard --install-daemon

你将选择：

• 本地 (Local) vs 远程 (Remote) 网关
• 认证 (Auth)：OpenAI Code (Codex) 订阅 (OAuth) 或 API 密钥。对于 Anthropic 我们推荐 API 密钥；也支持 claude setup-token。
• 提供商 (Providers)：WhatsApp 二维码登录，Telegram/Discord 机器人令牌，Mattermost 插件令牌等。
• 守护进程 (Daemon)：后台安装（launchd/systemd；WSL2 使用 systemd）
  • 运行时 (Runtime)：Node（推荐；WhatsApp/Telegram 需要）。不推荐使用 Bun。
• 网关令牌 (Gateway token)：向导默认会生成一个（即使在环回接口上）并将其存储在 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 复制到网关主机。

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

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 运行网关。

openclaw status
openclaw health
openclaw security audit --deep

openclaw channels login

通过 WhatsApp 扫描 → 设置 → 已关联设备。

WhatsApp 文档：WhatsApp

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

• Telegram: Telegram
• Discord: Discord
• Mattermost (插件): Mattermost

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

默认姿态：未知的私信会获得一个短代码，并且在批准之前不会处理消息。 如果你的第一条私信没有得到回复，请批准配对：

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

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

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 应用