OpenClawSkills
GitHub
快速开始 • 5 分钟阅读

入门指南

从零开始到第一次 AI 对话的最快路径。

目标：以最快速度从 零开始 第一次成功聊天（使用合理的默认配置）。

最快聊天方式： 打开控制界面（无需设置渠道）。运行 openclaw dashboard

然后在浏览器中聊天，或打开 http://127.0.0.1:18789/（在 Gateway 主机上）。

文档：仪表盘 和 控制界面。

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

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

如果您需要更详细的参考页面，请跳转至：向导, 设置, 配对, 安全。

沙箱注意事项： agents.defaults.sandbox.mode: "non-main" 使用 session.mainKey（默认 "main"），因此群组/渠道会话是沙箱化的。如果您希望主智能体始终在主机上运行，请设置显式的逐智能体覆盖：

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

前提条件

  • Node >=22
  • pnpm（可选；如果从源码构建则推荐安装）
  • 推荐： Brave Search API 密钥用于网络搜索。

最简单的方式：openclaw configure --section web (存储 tools.web.search.apiKey)。

参见 网络工具。

macOS：如果您计划构建应用程序，请安装 Xcode / CLT。如果仅使用 CLI + Gateway，Node 就足够了。

Windows：使用 WSL2（推荐 Ubuntu）。原生 Windows 未经测试，且工具兼容性较低。请参见 Windows (WSL2)。

Tutorial.step

安装 CLI（推荐）

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

安装选项（Shell 类型、非交互式、从 GitHub 安装）：安装。

Windows (PowerShell)：

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

替代方式（全局安装）：

Bash
npm install -g openclaw@latest
Bash
pnpm add -g openclaw@latest
Tutorial.step

运行上手引导向导（并安装服务）

Bash
openclaw onboard --install-daemon

您需要选择的内容：

  • 本地 vs 远程 Gateway
  • 认证：OpenAI Code (Codex) 订阅（OAuth）或 API 密钥。对于 Anthropic，我们推荐使用 API 密钥；claude setup-token 也受支持。
  • 提供商：WhatsApp 二维码登录、TG/Discord 机器人令牌等。
  • 守护进程：后台安装（launchd/systemd）
  • 运行时：Node（推荐；WhatsApp/TG 必需）。Bun 不推荐。
  • Gateway 令牌：向导默认会生成一个并将其存储在 gateway.auth.token。

向导文档：向导

Tutorial.step

认证：存储位置（重要）

  • 推荐的 Anthropic 路径： 设置 API 密钥（向导可以将其存储以供服务使用）。claude setup-token 如果您想复用 Claude Code 凭据，也受支持。
  • OAuth 凭据（旧版导入）：~/.openclaw/credentials/oauth.json
  • Auth Profile (OAuth + API Keys): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

无头/服务器提示：先在桌面机器上完成 OAuth，然后将 oauth.json 复制到 Gateway 主机上。

Tutorial.step

启动 Gateway

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

Bash
openclaw gateway status

手动运行（前台）：

Bash
openclaw gateway --port 18789 --verbose

仪表盘（本地回环）：http://127.0.0.1:18789/

如果配置了令牌，请将其粘贴到控制界面设置中（存储为 connect.params.auth.token）。

Tutorial.alert.warning

⚠️ Bun 警告（WhatsApp + Telegram）： Bun 在这些渠道上存在已知问题。如果您使用 WhatsApp 或 Telegram，请使用 Node。
Tutorial.step

快速验证（2 分钟）

Bash
openclaw status
openclaw health
openclaw security audit --deep
Tutorial.step

配对 + 连接您的第一个聊天界面

Tutorial.step

WhatsApp（二维码登录）

Bash
openclaw channels login

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

WhatsApp 文档：WhatsApp

Tutorial.step

Telegram / Discord / 其他

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

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

Tutorial.step

私信安全（配对审批）

默认策略：未知私信会收到一个短码，消息在批准之前不会被处理。

如果您的第一条私信没有收到回复，请批准配对：

Bash
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

配对文档：配对

Tutorial.step

从源码安装（开发）

如果您正在开发 OpenClaw 本身，请从源码运行：

Bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # auto-installs UI deps on first run
pnpm build
openclaw onboard --install-daemon

如果您尚未进行全局安装，请通过 pnpm openclaw ...（在仓库中）运行上手引导步骤。

pnpm build 也会打包 A2UI 资源；如果您只需要运行该步骤，请使用 pnpm canvas:a2ui:bundle。

Gateway（从此仓库）：

Bash
node openclaw.mjs gateway --port 18789 --verbose
Tutorial.step

端到端验证

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

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

如果 openclaw health 显示“未配置认证”，请返回向导设置 OAuth/密钥认证——智能体在没有认证的情况下将无法响应。

提示：openclaw status --all 是最佳的可粘贴只读调试报告。

健康探针：openclaw health（或 openclaw status --deep）向运行中的 Gateway 请求健康快照。

Tutorial.step

后续步骤（可选，但强烈推荐）