AI 编程教程中文版
官方教程中文版入门与安装

快速上手 OpenClaw

用 OpenClaw onboarding 跑通模型认证、Gateway、Dashboard 和第一条消息，确认最小闭环真的可用。

快速开始的目标不是学完所有配置，而是在最短路径里确认四件事：OpenClaw 已安装、模型认证可用、Gateway 正在跑、你能在 Control UI 里和 Agent 发第一条消息。

这一章用 10 分钟换什么：你不会先陷进 channels、cron、skills 或远程访问，而是先得到一个能对话、能诊断、能继续配置的本机 OpenClaw。

1. 先准备两样东西

快速开始只需要两样东西：

准备项为什么需要
Node.jsOpenClaw CLI 和 Gateway runtime 依赖 Node；官方推荐 Node 24，也支持 Node 22.14+
模型供应商 API keyonboarding 会引导你配置 Anthropic、OpenAI、Google 等 provider

检查 Node：

node --version

Windows 用户可以用原生 Windows，也可以用 WSL2。需要更完整本地工具链时，WSL2 通常更稳定。

API key 先准备好：onboarding 会问模型 provider 和认证信息。你可以先不接 Telegram / Discord，但不能没有模型认证。

2. 安装 OpenClaw

macOS / Linux / WSL2：

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

Windows PowerShell：

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

官方安装脚本默认会进入 onboarding。如果你安装时跳过了 onboarding，手动运行：

openclaw onboard --install-daemon

3. 跑 onboarding

openclaw onboard --install-daemon 会引导你完成：

  • 选择模型 provider。
  • 填入 API key 或完成对应认证。
  • 创建基础配置。
  • 安装并配置 Gateway daemon。
  • 创建默认 workspace 和启动文件。

普通用户优先走 onboarding，不要一开始手改 ~/.openclaw/openclaw.json。等跑通后，再用 openclaw configure、openclaw config set 或 Control UI 调整。

sequenceDiagram
    participant U as 你
    participant CLI as OpenClaw CLI
    participant GW as Gateway
    participant UI as Control UI
    participant Agent as Agent

    U->>CLI: openclaw onboard --install-daemon
    CLI->>GW: 写入基础配置并安装 daemon
    U->>CLI: openclaw gateway status
    CLI->>GW: 查询运行状态
    U->>UI: openclaw dashboard
    UI->>GW: 连接本机入口
    U->>Agent: 发送第一条消息
    Agent-->>U: 返回 AI 回复

onboarding 的产物不是一条命令：它应该同时留下配置、daemon、workspace 和可用的模型认证。少了任意一个，后面都会表现成“Gateway 跑了但 Agent 不能工作”。

4. 确认 Gateway 正在跑

openclaw gateway status

正常情况下你会看到 Gateway 监听在 18789 端口。默认本机地址是：

127.0.0.1:18789

Gateway 是 OpenClaw 的中枢。消息平台、Web UI、CLI、桌面端和移动端都通过它连接 Agent。

如果状态异常，先不要继续配置渠道。先看这些命令：

openclaw doctor
openclaw logs
openclaw health
命令先看什么
openclaw doctor安装、配置、环境是否有明显错误
openclaw logsGateway 启动、schema、认证或端口错误
openclaw health当前运行状态是否能被 Gateway 正常返回

5. 打开 Dashboard

openclaw dashboard

这会打开 Control UI。如果浏览器能加载，并且能看到聊天入口或配置入口，说明 Gateway 的本地 WebSocket / HTTP 入口可用。

也可以直接访问：

http://127.0.0.1:18789

如果打不开，按这个顺序判断：

现象先判断
浏览器打不开Gateway 是否真的在跑
端口连接失败18789 是否被占用或 Gateway 未启动
页面能打开但不能聊天模型认证或 Agent workspace 是否完整
页面配置异常openclaw.json 是否通过 schema 校验

6. 发送第一条消息

在 Control UI 聊天框里发一条简单消息，例如：

你现在能正常工作吗？请用一句话说明你的身份和当前 workspace。

能收到 AI 回复，就说明最小闭环已经跑通。

这条消息故意问“身份”和“workspace”，因为它能同时验证三件事：

  • Agent 能调用模型生成回复。
  • workspace 文件被正确加载。
  • Gateway 到 Control UI 的请求链路可用。

第一条消息不要测试复杂工具调用：不要一上来让它读全盘、执行 shell、接外部 API。先确认最小聊天链路，再逐步打开工具和渠道。

7. 常见下一步怎么选

跑通 Dashboard 之后，再决定下一步。

你想做什么下一步
手机上聊天看 Channels 文档，先从 Telegram 这类 bot token 路径开始
接团队群先读 pairing、allowlist、group mention 和安全边界
改模型、tools、sandbox读配置结构和 Gateway 配置
整理长期规则和记忆读 Agent Workspace
后台定时任务先读 Gateway 运行时，再碰 cron、hooks、heartbeat

OpenClaw 支持 Discord、Feishu、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo 等渠道。每个渠道都要单独处理 bot token、OAuth、webhook 或平台侧权限。

下一步只选一个方向：没跑通 Dashboard 就回到 Gateway；能聊天但身份不稳就看 workspace；准备接外部消息才进入 Channel。

8. 环境变量什么时候要动

如果你用服务账号、要改状态目录、或者要指定配置路径，官方列出几个关键变量：

OPENCLAW_HOME=...
OPENCLAW_STATE_DIR=...
OPENCLAW_CONFIG_PATH=...

普通本机使用不需要一开始就设置它们。只有迁移、多实例、服务化部署时再动。

不要为了“看起来专业”提前改路径：路径越多，排障越难。第一台机器先用默认路径跑通，再考虑服务化和多实例。

9. 本章自检

  1. onboarding 应该留下哪几类产物？
  2. Gateway 默认监听哪个本机端口？
  3. 第一条消息为什么要问身份和 workspace？

过关标准：你能用一句话说清 —— “快速开始不是配置完全部功能，而是验证安装、认证、Gateway、Control UI、Agent 回复这条最小链路。”

10. 接下来去哪

理解配置结构

跑通之后，再理解 openclaw.json、schema、热加载和密钥边界。

配置 Agent Workspace

如果第一条消息能回复，但身份和规则不稳定，下一步看 workspace。

Gateway 架构

从长期控制面继续理解 Gateway、Client、Node、WebChat 和远程入口。

11. 官方资料

安装 OpenClaw

基于官方 OpenClaw 安装教程，面向新手讲清推荐安装、Node 要求、替代路径、源码安装和安装后验证。

理解配置结构

理解 OpenClaw 配置结构：openclaw.json、JSON5、strict schema、热加载、last-known-good、环境变量和密钥边界。

本页目录

1. 先准备两样东西2. 安装 OpenClaw3. 跑 onboarding4. 确认 Gateway 正在跑5. 打开 Dashboard6. 发送第一条消息7. 常见下一步怎么选8. 环境变量什么时候要动9. 本章自检10. 接下来去哪11. 官方资料