入门指南

目标：从零开始 → 第一个可用的聊天（使用默认配置）尽可能快。

最快聊天方式：打开控制台 UI（无需通道设置）。运行 openclaw dashboard 在浏览器中聊天，或在网关主机上打开 http://127.0.0.1:18789/。

文档：Dashboard 和 Control UI。

推荐路径

使用 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.js ≥ 22
• pnpm（可选，但从源码构建时推荐）
• 推荐：Brave Search API 密钥用于网页搜索。最简单的方式： openclaw configure --section web（存储 tools.web.search.apiKey）。 参见 Web 工具。

macOS

如果你计划构建应用，需要安装 Xcode / CLT。仅 CLI + 网关的话，只需要 Node.js。

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 key；claude setup-token 也支持。
• 提供商：WhatsApp 扫码登录、Telegram/Discord Bot Token、Mattermost 插件 Token 等
• 守护进程：后台安装（launchd/systemd；WSL2 使用 systemd）
  • 运行时：Node（推荐；WhatsApp/Telegram 需要）。Bun 不推荐。
• 网关令牌：向导现在默认生成一个令牌（即使在回环上）并将其存储在 gateway.auth.token 中

文档：安装向导

认证：存储位置（重要）

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

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

• 认证配置（OAuth + API keys）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json

无头/服务器提示：如果你的网关运行在没有浏览器的服务器上，建议先在本地机器完成 OAuth 认证，然后手动复制 oauth.json 到服务器。

3) 启动网关

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

openclaw gateway status

手动运行（前台）：

openclaw gateway --port 18789 --verbose

控制台 UI（本地环回）：http://127.0.0.1:18789/ 如果配置了令牌，请将其粘贴到控制台 UI 设置中（存储为 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

Telegram / Discord / 其他

向导可以为你写入 Token/配置。如果你偏好手动配置，从以下开始：

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

Telegram 私聊提示：你的第一条私聊会返回一个配对验证码。批准它（见下一步），否则 Bot 不会回复。

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 显示"未配置认证"，请回到向导并设置 OAuth/key auth —— 没有它智能体将无法回复。

提示：openclaw status --all 是最佳的只读调试报告。 健康检查：openclaw health（或 openclaw status --deep）询问运行中的网关获取健康快照。

下一步（可选，但很棒）

• macOS 菜单栏应用 + 语音唤醒：macOS 应用
• iOS/Android 节点（Canvas/相机/语音）：节点
• 远程访问（SSH 隧道 / Tailscale Serve）：远程访问 和 Tailscale
• 常驻 / VPN 设置：远程访问、EXE 开发版、Hetzner、macOS