OpenClaw 中文文档 — 快速上手

本文是 OpenClaw 的快速上手指南，目标是从零开始完成第一次 AI 对话。内容基于官方文档和实际部署验证，覆盖安装、Onboarding 配置和 Gateway 启动的完整流程。

环境要求

OpenClaw 运行在 Node.js 之上，版本要求如下：

版本	支持状态	说明
Node 24	推荐	当前推荐版本
Node 22 LTS	兼容	最低版本 22.16
Node 20 及以下	不支持	启动时会报错

验证当前版本：

node --version

值得注意的是，OpenClaw 对 Node 版本的要求比较激进——直接要求 22.16+ 或 24。这个决策背后的考量应该是充分利用新版本的 ESM、WebSocket 和性能改进，避免为旧版本做兼容。

安装

OpenClaw 提供官方安装脚本，覆盖主流平台。

macOS / Linux / WSL2

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

脚本会自动检测系统环境、下载二进制文件、配置 PATH。

Windows（PowerShell）

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

Windows 环境推荐使用 WSL2 运行 OpenClaw。原生 Windows 存在路径处理和进程管理方面的兼容性问题。

安装完成后验证：

openclaw --version

其他安装方式（Docker、Podman、Nix、Ansible 等）将在下一篇文章中详细对比。

Onboarding 向导

OpenClaw 的 Onboarding 向导是一个一站式配置工具，在一个引导流程中完成 Gateway 配置、模型认证和渠道接入：

openclaw onboard --install-daemon

--install-daemon 参数会在配置完成后将 Gateway 注册为系统服务（macOS 使用 LaunchAgent，Linux/WSL2 使用 systemd 用户单元）。

QuickStart 与 Advanced

向导提供两种模式：

QuickStart（默认配置）：

• 本地 Gateway，回环地址绑定
• 端口 18789
• Token 认证（自动生成）
• 工具策略默认 tools.profile: "coding"
• DM 隔离模式 session.dmScope: "per-channel-peer"
• Tailscale 暴露关闭

Advanced（完全掌控）：

• 逐步展示每个配置项：模式、工作区、Gateway、渠道、守护进程、Skills

从架构层面来看，QuickStart 的默认值选择是经过考量的：per-channel-peer 的 DM 隔离确保不同渠道的同一联系人拥有独立会话；coding 工具配置在保留文件系统和运行时工具的同时，避免了 full 配置可能带来的安全风险。

向导配置流程

向导在本地模式下依次完成以下配置：

1. 模型和认证：选择 AI 供应商（Anthropic、OpenAI 等），配置 API Key 或 OAuth。支持自定义供应商（OpenAI 兼容、Anthropic 兼容或自动检测模式）。安全建议：优先使用最新一代强模型，较弱模型更易受 prompt 注入影响
2. 工作区：Agent 文件存放目录，默认 ~/.openclaw/workspace，生成引导文件
3. Gateway：端口、绑定地址、认证模式。即使在回环地址上也会生成 Token
4. 消息渠道：可选配置 WhatsApp、Telegram、Discord、Google Chat、Mattermost、Signal、BlueBubbles 或 iMessage
5. 守护进程：注册系统服务，开机自启
6. 健康检查：启动 Gateway 并验证运行状态
7. Skills：安装推荐的技能包和可选依赖

向导还包含一个网页搜索配置步骤，可选择 Perplexity、Brave、Gemini、Grok 或 Kimi 作为搜索供应商，使 Agent 能够使用 web_search 工具。此步骤也可之后通过 openclaw configure --section web 补充配置。

重新运行向导不会清除已有配置，除非显式选择 Reset 或传入 --reset 参数。

Gateway 验证

向导完成后，Gateway 应已作为后台服务运行：

openclaw gateway status

如需在前台运行（便于查看日志和排查问题）：

openclaw gateway --port 18789

Control UI

OpenClaw 提供 Web 控制面板，无需配置任何消息渠道即可直接与 AI 对话：

openclaw dashboard

或直接访问 http://127.0.0.1:18789/。

相比于先配置 WhatsApp 或 Telegram 再测试，Control UI 提供了一个零配置的聊天入口。实测下来，这个设计降低了首次体验的门槛——用户可以先验证 Agent 能力，再决定接入哪些渠道。

命令行消息测试

配置了消息渠道后，可通过 CLI 发送测试消息：

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

环境变量

如需自定义目录位置，OpenClaw 支持以下环境变量：

变量	用途
OPENCLAW_HOME	主目录
OPENCLAW_STATE_DIR	状态目录
OPENCLAW_CONFIG_PATH	配置文件路径

后续配置

初始向导完成后，可通过以下命令进行增量配置：

openclaw configure             # 重新配置
openclaw agents add <name>     # 添加新 Agent

openclaw agents add 会创建拥有独立工作区、会话和认证 profile 的 Agent，适用于多 Agent 路由场景。

小结

至此，你应该拥有：

• 一个运行中的 Gateway 进程（后台服务或前台模式）
• 已配置的 AI 模型认证
• 通过 Control UI 的聊天能力
• 可选的消息渠道连接

本文是 OpenClaw 中文文档系列的第二篇。下一篇将详细对比各种安装方式（CLI 脚本、Docker、Podman、Nix、Ansible），分析各自适用场景。

---

完整中文文档：OpenClaw 中文文档

GitHub 仓库：openclaw/openclaw