AI 原生开放教材

外观

Awesome OpenClaw Tutorial（中文）清单与速查·中文原文 ↗原件 ↓仓库 ↗

国内一键安装（推荐） ​

🇨🇳 国内用户推荐：使用官方中文版一键安装脚本，速度快、配置简单。

为什么选择国内版？ ​

国内版相比国际版具有多项本地化优势，如表 2-3 所示。

表 2-3 国内版优势

优势说明
⚡ 速度快使用国内镜像源，下载速度快
🇨🇳 中文友好完整中文界面和提示
📦 一键安装自动配置所有依赖
🎯 开箱即用预配置国内常用服务
💰 成本优化默认配置国产模型

image-20260213122830687

前置要求 ​

必需环境：

  • Node.js 24（推荐）/ 22.16+（兼容路径）（必需）
  • pnpm（可选，推荐用于源码构建）

推荐配置：

  • Brave Search API 密钥（用于网络搜索）
  • 可通过 openclaw-cn configure --section web 配置

系统要求：

  • macOS：需要 Xcode / Command Line Tools（仅 CLI + Gateway 需要 Node.js）
  • Windows：强烈推荐使用 WSL2（Ubuntu），原生 Windows 未经测试
  • Linux：Ubuntu 20.04+、Debian、CentOS

快速开始 ​

macOS/Linux 安装 ​

bash
# 使用国内官方安装脚本
curl -fsSL https://clawd.org.cn/install.sh | bash

Windows 安装 ​

使用 PowerShell（管理员权限）：

powershell
# 使用国内官方安装脚本
iwr -useb https://clawd.org.cn/install.ps1 | iex

⚠️ Windows 用户注意：强烈推荐使用 WSL2（Ubuntu），原生 Windows 支持有限。

WSL2 安装步骤：

powershell
# 1. 安装 WSL2
wsl --install

# 2. 重启电脑

# 3. 在 WSL2 中运行 Linux 安装命令
curl -fsSL https://clawd.org.cn/install.sh | bash

全局安装（替代方案） ​

如果一键脚本失败，可以使用 npm 全局安装：

bash
# 使用 npm
npm install -g openclaw-cn@latest

# 或使用 pnpm（推荐）
pnpm add -g openclaw-cn@latest

运行入门向导 ​

安装完成后，运行配置向导：

bash
# 运行入门向导并安装后台服务
openclaw-cn onboard --install-daemon

配置向导流程 ​

向导会引导你完成以下配置：

1. 选择网关模式：

  • 本地网关（推荐）：Gateway 运行在本机
  • 远程网关：Gateway 运行在服务器

2. 配置认证：

  • OpenAI Code（Codex）订阅（OAuth）
  • API 密钥（推荐用于 Anthropic）
  • 也支持 claude setup-token

3. 选择 AI 提供商：

  • 推荐：Kimi、DeepSeek、GLM-4（国产模型）
  • 可选：Claude、GPT（需要 API key）

4. 配置聊天平台（可选）：

  • WhatsApp：QR 扫码登录
  • Telegram：输入 Bot Token
  • Discord：输入 Bot Token
  • Mattermost：插件令牌
  • 飞书/企微/钉钉：输入应用凭证

5. 安装后台服务（推荐）：

  • macOS：使用 launchd
  • Linux：使用 systemd
  • WSL2：使用 systemd
  • 运行时：Node（推荐，WhatsApp/Telegram 必需）

6. 网关令牌：

  • 向导默认生成一个令牌
  • 存储在 gateway.auth.token 中
  • 即使在回环地址上也会生成

认证配置说明 ​

认证存储位置（重要）：

  • 推荐的 Anthropic 路径：设置 API 密钥（向导可存储）
  • OAuth 凭据（旧版导入）：~/.openclaw/credentials/oauth.json
  • 认证配置文件：~/.openclaw/agents/<agentId>/agent/auth-profiles.json

无头/服务器提示：

  • 先在普通机器上完成 OAuth
  • 然后将 oauth.json 复制到网关主机

启动 Gateway ​

如果安装了后台服务，Gateway 应该已经在运行：

bash
# 检查 Gateway 状态
openclaw-cn gateway status

手动运行（前台）：

bash
# 在前台运行，查看实时日志
openclaw-cn gateway --port 18789 --verbose

Dashboard 访问：

本地回环地址：http://127.0.0.1:18789/

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

⚠️ Bun 警告（WhatsApp + Telegram）：Bun 在这些渠道上有已知访问题。如果使用 WhatsApp 或 Telegram，请使用 Node 运行网关。

快速验证（2分钟） ​

bash
# 检查状态
openclaw-cn status

# 健康检查
openclaw-cn health

配对 + 连接聊天界面 ​

WhatsApp（二维码登录） ​

bash
# 登录 WhatsApp
openclaw-cn channels login

通过 WhatsApp → 设置 → 已连接的设备 扫描二维码。

Telegram / Discord / 其他 ​

向导可以为你写入令牌/配置。如果手动配置：

Telegram：

bash
openclaw-cn channels add \
  --channel telegram \
  --token "YOUR_BOT_TOKEN"

Discord：

bash
openclaw-cn channels add \
  --channel discord \
  --token "YOUR_BOT_TOKEN"

💡 Telegram 私信提示：首次私信会返回配对码，需要批准后机器人才会响应。

私信安全（配对审批） ​

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

如果首次私信没有得到回复，需要批准配对：

bash
# 查看配对列表
openclaw-cn pairing list whatsapp

# 批准配对
openclaw-cn pairing approve whatsapp <code>

从源码运行（开发布） ​

如果需要修改 OpenClaw 本身，可以从源码运行：

bash
# 克隆仓库
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

# 安装依赖
pnpm install

# 构建 UI（首次运行时自动安装 UI 依赖）
pnpm ui:build

# 构建项目
pnpm build

# 运行入门向导
openclaw-cn onboard --install-daemon

如果还没有全局安装，可以从仓库中通过 pnpm openclaw-cn ... 运行命令。

从源码运行 Gateway：

bash
node dist/entry.js gateway --port 18789 --verbose

端到端验证 ​

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

bash
# 发布送测试消息
openclaw-cn message send --target +15555550123 --message "Hello from OpenClaw"

如果 openclaw-cn health 显示 "no auth configured"，需要返回向导设置 OAuth/密钥认证。

调试提示：

  • openclaw-cn status --all：最佳的只读调试报告
  • openclaw-cn health：向运行中的网关请求健康快照
  • openclaw-cn status --deep：深度状态检查

配置文件位置 ​

📖 详细说明: 完整的配置文件结构和使用指南请参考 配置文件结构完整指南

bash
# 主配置文件
~/.openclaw/openclaw.json

# 认证配置
~/.openclaw/agents/<agentId>/agent/auth-profiles.json

# OAuth 凭据（旧版）
~/.openclaw/credentials/oauth.json

# 日志文件件
~/.openclaw/logs/gateway.log

国内版特色功能 ​

1. 预配置国产模型：

  • Kimi（月之暗面）
  • DeepSeek（深度求索）
  • GLM-4（智谱 AI）
  • 通义千访问（阿里）
  • 文心一言（百度）

2. 国内平台集成：

  • 飞书（字节跳动）
  • 企业微信（腾讯）
  • 钉钉（阿里）
  • QQ（腾讯）

3. 优化的网络配置：

  • 使用国内镜像源
  • 优化 API 访问速度
  • 支持代理配置

常见访问题 ​

Q1: 安装失败怎么怎么办？

bash
# 检查 Node.js 版本（需要 22+）
node --version

# 如果版本过低，使用 nvm 升级
nvm install 22
nvm use 22

Q2: 如何更新到最新版本？

bash
# 重新运行安装脚本
curl -fsSL https://clawd.org.cn/install.sh | bash

Q3: 如何卸载？

bash
# 停止服务
openclaw-cn gateway stop

# 卸载
npm uninstall -g openclaw-cn

# 删除配置（可选）
rm -rf ~/.openclaw

Q4: 支持哪些系统？

  • ✅ macOS 12+
  • ✅ Linux（Ubuntu 20.04+、Debian、CentOS）
  • ✅ Windows 10/11（通过 WSL2）

Q5: 配置向导卡住怎么怎么办？

bash
# 按 Ctrl+C 中断

# 检查网关是否运行
openclaw-cn gateway status

# 重新启动网关并重试
openclaw-cn gateway restart
openclaw-cn onboard

Q6: 健康检查显示 "no auth configured"

需要配置认证：

bash
# 重新运行向导
openclaw-cn onboard

# 或手动配置 API 密钥
openclaw-cn configure --section auth

下一步（可选，但很棒） ​

  • macOS 菜单栏应用 + 语音唤醒：macOS 应用
  • iOS/Android 节点（Canvas/摄像头/语音）：节点
  • 远程访问（SSH 隧道 / Tailscale 服务）：远程访问
  • 始终在线 / VPN 设置：Tailscale

下一步 ​

安装完成后，可以：

  1. 配置 AI 模型（见下文"API配置指南"）
  2. 连接聊天平台（见第9章节：多平台集成）
  3. 安装 Skills（见第8章节：Skills扩展）
  4. 开始使用（见第3章节：快速上手)