快速开始指南
本指南帮助你从零开始运行 OpenClaw：从环境准备、CLI 安装、入门向导到启动网关与配置第一个通道，并完成一次完整对话验证。无论你是个人使用还是为团队部署，这里都提供了必要的步骤与注意事项。
准备工作
在开始使用 OpenClaw 之前，请确保满足以下环境与账号条件。
环境要求
| 项目 | 要求说明 |
|---|---|
| Node.js | 版本 >= 22，推荐使用 LTS（如 22.x）。可用 node -v 检查。 |
| 包管理器 | npm 或 yarn；若从源码参与开发，可选 pnpm。 |
| 网络 | 能访问 npm 源与各通道/模型 API；若需搜索能力，可选 Brave Search API。 |
| 磁盘与权限 | 安装与运行目录具备写权限；持久化数据与日志会占用一定磁盘空间。 |
可选但推荐的前置准备
- 模型 API Key：至少准备一个你要使用的模型提供商的 API Key（如 OpenAI、Claude、MiniMax、Kimi、GLM 等），以便在入门向导中直接配置。
- 通道账号或应用：若计划先接入某一通道，可提前在该平台创建 Bot 或应用（如 Telegram Bot、微信测试号、钉钉/飞书应用），以便在向导中填写 Token 或凭证。
- Brave Search API Key（可选）：若希望 Agent 具备网络搜索能力，可提前申请并准备 Key。
安装 CLI
OpenClaw 通过命令行工具 openclaw-cn 进行安装、配置与日常运维。
使用 curl 安装（推荐）
在终端执行（具体安装脚本地址以 官方文档 为准）：
curl -fsSL https://openclaw.example.com/install.sh | sh
安装完成后，在终端执行：
openclaw-cn --version
能正常输出版本号即表示安装成功。
使用 npm 全局安装
若你习惯使用 npm：
npm install -g openclaw-cn
安装路径可能受 npm config get prefix 影响；若执行 openclaw-cn 提示命令未找到，可将该 prefix 下的 bin 目录加入环境变量 PATH，或改用 npx openclaw-cn 调用。
验证安装
# 查看版本
openclaw-cn --version
# 查看帮助（可选）
openclaw-cn --help
openclaw-cn onboard --help
openclaw-cn gateway --help
入门向导流程
安装完成后，建议使用入门向导一次性完成：模型与认证、网关、通道与（可选）守护进程的配置。
运行入门向导
在希望安装或运行 OpenClaw 的目录下执行：
openclaw-cn onboard --install-daemon
--install-daemon 表示在向导中可选安装系统服务（如 systemd 单元），便于开机自启或后台常驻；若仅本地临时试用，也可在向导中跳过守护进程安装。
向导会引导你完成的步骤
-
模型与认证
- 选择要使用的模型提供商（如 OpenAI、Claude、MiniMax、Moonshot/Kimi、GLM 等）。
- 填写对应的 API Key 或认证信息（按各厂商要求）。
- 可配置多个模型，供不同 Agent 或回退使用。
-
网关
- 配置网关监听地址与端口（例如默认 18789）。
- 若部署在服务器且需被外网访问（如接收 Webhook），需确保该端口在防火墙/安全组中放行。
-
通道
- 选择要接入的通道（如 WhatsApp、Telegram、Discord、微信、钉钉、飞书等）。
- 按提示完成该通道的对接：例如 Telegram 需 Bot Token，微信需在开放平台创建应用并配置服务器地址等。
- 不同通道的详细步骤以官方文档或向导内说 明为准。
-
守护进程（可选）
- 若选择安装，向导会生成并注册系统服务，使网关在系统重启后自动拉起。
- 未安装时，需手动执行
openclaw-cn gateway并保持进程运行。
按提示逐步完成即可在本地生成配置文件与运行环境；后续若要修改，可直接编辑配置文件或重新运行向导（视版本是否支持覆盖）。
启动网关
向导完成后，启动网关以接收各通道消息并转发给 Agent：
openclaw-cn gateway --port 18789
- 若在向导中使用了其他端口，请将
--port改为一致，或通过配置文件指定，具体以版本文档为准。 - 网关启动后需保持该终端运行，或通过已安装的守护进程在后台运行。
- 看到类似 “Gateway listening on port 18789” 的日志即表示网关已就绪。
使用守护进程时
若已通过向导安装守护进程，可使用系统服务管理命令启动/停止/查看状态，例如（以 systemd 为例）：
# 启动
sudo systemctl start openclaw-gateway
# 开机自启
sudo systemctl enable openclaw-gateway
# 查看状态
sudo systemctl status openclaw-gateway
# 查看日志
journalctl -u openclaw-gateway -f
具体服务名以向导生成或官方文档为准。
连接通道与首次对话
不同通道的对接方式略有差异，均在「入门向导」或 官方文档 中有对应说明。
海外常见通道（示例）
- Telegram：在 @BotFather 创建 Bot，获取 Token，在向导或配置中填写；若需 Webhook，需保证网关有公网可访问的 HTTPS 地址。
- WhatsApp / Discord：在对应开发者平台创建应用或 Bot，获取凭证后填入 OpenClaw 配置。
- iMessage：通常需在 macOS 环境下配合额外组件使用，以官方文档为准。
国内常见通道（示例）
- 微信：在微信开放平台创建公众号/小程序/企业微信应用，配置服务器 URL 与 Token，并在 OpenClaw 中填写对应配置。
- 钉钉 / 飞书：在各自开放平台创建应用，获取 AppKey/AppSecret 等，配置 Webhook 或回调地址指向你的网关。
配置完成后，在相应平台向你的 Bot 或应用发送一条消息；若网关与路由正常，应能在 OpenClaw 侧收到并由配置的 Agent 回复，从而完成首次端到端对话验证。
配对与安全（私信场景）
若使用私信或一对一场景，强烈建议在配置中开启配对审批：只有经过你（或管理员）确认的用户才能与 Agent 对话，避免未授权访问或滥用。
- 开启方式：在配置或入门向导中查找「配对」「审批」「私信安全」等选项，按说明开启。
- 开启后，新用户首次私信可能需你在控制台或管理界面中通过审批，通过后对话才会正常进行。
具体入口与交互以当前版本文档为准。
配置文件与后续修改
入门向导会在本地生成配置文件（路径与格式以版本为准，常见为项目目录下的 config 或用户目录下的 .openclaw 等）。后续若需：
- 更换模型或 API Key：修改配置中对应项或环境变量，重启网关。
- 新增或修改通道：在配置中增加或编辑通道块，重启网关。
- 调整路由或多 Agent：编辑路由与 Agent 配置，重启网关。
建议将非敏感配置纳入版本控制，敏感信息仅通过环境变量或加密配置注入；详见 开发指南 与 最佳实践。
验证清单
完成本指南后，建议确认以下项：
- CLI 已安装且
openclaw-cn --version正常。 - 已运行入门向导并完成模型、网关、至少一个通道的配置。
- 网关能成功启动（前台或守护进程），且端口可访问（若需外网）。
- 在至少一个通道上完成一次「用户发消息 → Agent 回复」的端到端验证。
- 若使用私信，已按需开启配对审批并测试通过流程。