OpenClaw 中文版安装全攻略：从零开始到完全搞定（不踩坑版）OpenClaw 中文版安装全攻略：从零开始到完全搞定

OpenClaw 中文版安装全攻略：从零开始到完全搞定（不踩坑版）

本文将教你如何把 OpenClaw-CN 搞上你的机器。严格按照官方文档核实，确保每一步都准确无误——至少比隔壁老王的教程靠谱。

前言：OpenClaw 是什么？能吃吗？

OpenClaw 是一个私有化部署的 AI 智能助手，让你能在各种聊天平台（飞书、Telegram、Signal、WhatsApp 等）里跟 AI 对话。

中文社区版特点：

🇨🇳 完整中文化 — CLI、Web 控制界面、配置向导全部汉化，不用再看谷歌翻译的脸色
🏠 本地优先 — 数据存储在你自己的设备上，隐私可控（别让你的 AI 聊天记录被卖到暗网）
📱 多渠道支持 — WhatsApp、Telegram、Slack、Discord、Signal、iMessage、微信（开发中，别催）
🔧 技能扩展 — 内置技能 + 自定义工作区技能，想让它干啥就干啥
🚀 国内优化 — 所有依赖包已构建为 npm 包，淘宝镜像源可直接下载，告别 GitHub 超时

重要声明： 本教程介绍的是 OpenClaw 中文社区版（openclaw-cn），非官方版本。目的是让国内用户快速接入，更适配国内网络环境。如果你是原版死忠粉，出门左转去 GitHub 搜 openclaw/openclaw。

OpenClaw 主界面预览

OpenClaw 主界面

看，这就是你要安装的东西。界面是不是很清爽？比某些收费软件好看多了。

一、架构介绍：别急着装，先搞懂原理

在开始安装之前，了解一下 OpenClaw 的架构，免得你装完了还不知道它是怎么工作的。

整体架构

OpenClaw 采用网关（Gateway）架构，简单来说就是：

用户（飞书/Telegram/等） ↔ OpenClaw Gateway ↔ AI 模型（OpenAI/Claude/国产模型）
                                    ↓
                              本地工作区
                                    ↓
                              技能/插件系统

核心组件：

Gateway（网关） — 大脑中枢，负责：
- 接收来自各个聊天平台的消息
- 调用 AI 模型生成回复
- 管理会话和上下文
- 调用技能和插件
Channels（渠道） — 消息通道，支持：
- 飞书、Telegram、WhatsApp、Slack、Discord、Signal、iMessage 等
- 每个渠道可以配置多个账号
Agents（智能体） — AI 核心，负责：
- 调用各种 AI 模型（OpenAI、Anthropic、智谱、DeepSeek 等）
- 处理对话上下文和记忆
- 执行技能和工具调用
Workspace（工作区） — 本地数据，包括：
- 配置文件（openclaw.json）
- 记忆文件（MEMORY.md）
- 技能和插件
- 日志文件
Skills（技能） — 扩展能力，比如：
- GitHub 集成
- 日历管理
- 邮件处理
- 智能家居控制

为什么要用网关架构？

✅ 统一接口 — 一个网关连接所有聊天平台，不用每个平台都单独配置
✅ 本地控制 — 数据在你自己手里，不用担心被卖到广告公司
✅ 灵活扩展 — 想加新功能就装技能，想换模型就改配置
✅ 隐私安全 — 默认本地运行，不经过第三方服务器

群组消息处理流程

如果你打算在群里用 OpenClaw，了解一下它是怎么处理群组消息的：

群组消息流程

看不懂图？没关系，我来解释：

群组消息 → 收到群里有人说话
群组策略检查 → 这个群是否启用 OpenClaw？
- disabled：直接丢弃，不处理
- open：所有人都能用
- allowlist：只有白名单里的人能用
白名单检查 → 这个人在不在白名单里？
- 不在：丢弃消息
- 在：继续处理
提及检查 → 需要 @机器人才回复吗？
- 不需要：存储上下文，但不回复
- 需要：调用 AI 生成回复
回复 → 发送回复到群里

为什么这么设计？

避免机器人被群里的闲聊刷屏（省 API 费用）
权限控制，不是谁都能用
上下文管理，记住之前的对话

二、快速安装（推荐）：一条命令搞定，别搞复杂了

官方推荐的一键安装

最简单的方式（适合懒人）：

curl -fsSL https://clawd.org.cn/install.sh | bash

这个脚本会自动：

✅ 检测并安装 Node.js（如果未安装，省得你自己折腾）
✅ 安装 Git（如果需要）
✅ 处理权限问题（别再问我为什么 sudo 不行了）
✅ 安装 openclaw-cn
✅ 自动运行配置向导

适用场景：

macOS 或 Linux 系统
首次安装，没有 Node.js 环境
希望自动处理所有依赖
你懒得手动配置

友情提示： 如果你连 curl 都没有，那建议先学习一下 Linux 基础。这不是嘲讽，是真的。

国内用户加速：

如果 curl 速度慢（虽然已经很快了），可以先配置镜像源：

# 设置 npm 镜像源（可选，脚本会自动检测）
export NPM_REGISTRY=https://registry.npmmirror.com
curl -fsSL https://clawd.org.cn/install.sh | bash

三、手动安装：适合已有 Node.js 环境（或者你就是爱折腾）

系统要求

支持的操作系统：

macOS 12+（Apple Silicon 或 Intel，都行，别问 M1/M2 支不支持）
Linux（Ubuntu、Debian、CentOS 等主流发行版）
Windows 10/11（通过 WSL2，原生支持？你想多了）

必需软件：

Node.js ≥ 22（⚠️ 这是硬性要求，别拿 Node 18 来碰瓷，也别问我为什么 16 不行）
npm 或 pnpm（pnpm 更快，但 npm 更稳定，你自己选）
Git（某些功能需要，比如技能安装）

检查你的环境

# 检查 Node.js 版本
node -v
# 应该输出 v22.x.x 或更高

# 检查 npm
npm -v

如果版本低于 22，或者提示 command not found，说明你需要安装或升级 Node.js。别想着用系统自带的包管理器，版本老得像 90 年代的产物。

安装 Node.js

方式一：使用 nvm（推荐，至少比系统包管理器靠谱）

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc  # 或 ~/.zshrc

# 安装 Node.js 22
nvm install 22
nvm use 22

# 验证
node -v  # 应该输出 v22.x.x

方式二：官方安装包

访问 Node.js 官网下载 LTS 版本（≥22）。记得选 LTS，别选 Current，除非你喜欢当小白鼠。

方式三：使用一键脚本（如果你不想看上面的废话）

如果不想手动安装，直接用官方一键安装脚本：

curl -fsSL https://clawd.org.cn/install.sh | bash

看见没？又绕回来了。所以为什么不一开始就用这个？

安装 OpenClaw-CN

使用 npm：

npm install -g openclaw-cn@latest

使用 pnpm：

pnpm add -g openclaw-cn@latest

国内用户加速：

# 设置淘宝镜像源
npm config set registry https://registry.npmmirror.com
npm install -g openclaw-cn@latest

常见坑：

❌ 如果报错 EACCES，说明权限不够：
```
sudo npm install -g openclaw-cn@latest
```
❌ 如果提示 Node 版本过低，先升级 Node.js（别问我怎么升，看上面）
❌ 如果安装卡住不动，换镜像源（看上面）

验证安装

openclaw-cn --version

如果输出版本号（如 0.1.7），恭喜你，安装成功！如果提示 command not found，那你可能需要重新读一遍上面的步骤。

四、从源码构建：适合开发者（或者你就是爱折腾源码）

如果你需要修改源码或参与开发，可以从源码构建。普通人请跳过这一节。

# 克隆仓库
git clone https://github.com/jiulingyun/openclaw-cn.git
cd openclaw-cn

# 安装依赖（推荐使用 pnpm）
pnpm install

# 构建前端 UI
pnpm ui:build

# 构建
pnpm build

# 运行配置向导
pnpm openclaw-cn onboard --install-daemon

五、初始化配置：让 OpenClaw 认识你

运行配置向导

openclaw-cn onboard --install-daemon

这个命令会：

引导你完成基础配置
选择你的聊天平台（飞书、Telegram 等）
配置 AI 模型（OpenAI、Anthropic、国产大模型等）
安装守护进程（让 OpenClaw 在后台运行）

友情提示： 仔细读每一行提示，别一路回车下去，否则你会得到一个默认配置的 OpenClaw，然后发现啥也干不了，又回来骂教程写得不好。

兼容性： 旧版本 clawdbot-cn 命令仍然可用，作为别名指向 openclaw-cn。所以你不用改脚本。

六、启动 OpenClaw：见证奇迹的时刻（或者报错的时刻）

启动网关

# 前台运行（带详细日志，方便看哪里出错了）
openclaw-cn gateway --port 18789 --verbose

# 后台运行（生产环境推荐）
openclaw-cn gateway --port 18789 --daemon

检查状态

openclaw-cn status

如果看到一堆绿色的状态指示，恭喜你，你成功了！如果看到一堆红色的错误，对不起，你还得继续往下看。

查看日志

# 使用命令查看
openclaw-cn logs

# 或直接查看日志文件
tail -f ~/.openclaw/logs/gateway.log

如果遇到问题，先看日志，别无脑报 bug。90% 的问题都是配置错误或权限问题。

七、配置文件详解：别搞乱了

配置文件位置

配置文件在 ~/.openclaw/openclaw.json（Linux/macOS）或 %APPDATA%\.openclaw\openclaw.json（Windows）。

注意： 不是 config.json，也不是 settings.json，是 openclaw.json。别问我为什么，问开发者去。

最小配置示例

{
  "agent": {
    "model": "anthropic/claude-opus-4-5"
  }
}

就这几行？ 是的，最小配置就这么简单。别一上来就搞复杂的配置，先跑起来再说。

完整配置示例

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "zai/glm-5",
        "fallbacks": ["zai/glm-4.7"]
      },
      "models": {
        "zai/glm-5": {
          "alias": "GLM-5"
        },
        "zai/glm-4.7": {}
      },
      "workspace": "/Users/你的用户名/.openclaw/workspace"
    }
  },
  "auth": {
    "profiles": {
      "zai:default": {
        "provider": "zai",
        "mode": "api_key"
      }
    }
  },
  "channels": {
    "feishu": {
      "accounts": {
        "feishu-bot": {
          "appId": "cli_xxxxxxxxxxxxx",
          "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxx",
          "domain": "feishu",
          "enabled": true
        }
      }
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "your-token-here"
    }
  }
}

重要： API 密钥别泄露！别把 openclaw.json 发到 GitHub 上，别告诉你的前女友，别写在便利贴上贴在显示器上。

八、飞书配置详解（谁让你是最常用且最复杂呢）

创建飞书应用

步骤1：访问飞书开放平台

访问飞书开放平台，登录你的飞书账号。

步骤2：创建应用

创建飞书应用

选择"创建企业自建应用"，填写应用名称（比如"我的AI助手"，别用"智能助手"这种烂大街的名字），选择应用类型（建议选择"机器人"）。

步骤3：获取应用凭证

获取应用凭证

进入应用详情页，找到"凭证与基础信息"，记下 App ID 和 App Secret。

友情提示： App Secret 只显示一次，记得复制保存。别到时候找不到又来问我。

步骤4：配置权限

配置权限

进入"权限管理"，开启以下权限：

im:message（接收和发送消息）
im:message:group_at_msg（群组消息）
contact:user.base:readonly（读取用户信息）

别问我为什么需要这些权限，你自己想想 AI 怎么接收消息。

步骤5：启用机器人能力

启用机器人能力

在"机器人能力"中，启用机器人功能。

步骤6：设置事件订阅

设置事件订阅

在"事件订阅"中：

填写你的服务器地址（必须是公网可访问的 URL）
启用 im.message.receive_v1 事件

重要： 事件订阅地址必须可以通过公网访问，别用 localhost。如果你不知道什么是公网地址，那建议先学习网络基础。

在 OpenClaw 中配置

方式一：通过配置向导

openclaw-cn onboard

方式二：手动编辑配置文件

编辑 ~/.openclaw/openclaw.json：

{
  "channels": {
    "feishu": {
      "accounts": {
        "feishu-bot": {
          "appId": "cli_xxxxxxxxxxxxx",
          "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxx",
          "domain": "feishu",
          "enabled": true
        }
      }
    }
  },
  "plugins": {
    "load": {
      "paths": ["/usr/local/lib/node_modules/openclaw-cn/extensions/feishu"]
    },
    "entries": {
      "feishu": {
        "enabled": true
      }
    }
  }
}

常见坑：

❌ 事件订阅地址必须可以通过公网访问，别用 localhost
❌ 权限要开启，否则你的机器人啥也收不到
❌ 记得在飞书群里添加机器人，否则它是个孤家寡人
❌ App ID 和 App Secret 别填反了（别笑，真有人这么干）

重启网关

配置完成后，重启网关使配置生效：

openclaw-cn gateway restart

九、常用命令速查（收藏这个，别到处找）

# ========== 安装相关 ==========
# 一键安装（推荐，最简单）
curl -fsSL https://clawd.org.cn/install.sh | bash

# 手动安装
npm install -g openclaw-cn@latest

# 更新
npm update -g openclaw-cn@latest

# 查看版本
openclaw-cn --version

# ========== 配置相关 ==========
# 运行配置向导
openclaw-cn onboard

# 配置向导 + 安装守护进程
openclaw-cn onboard --install-daemon

# ========== 网关相关 ==========
# 前台启动（调试用）
openclaw-cn gateway --port 18789 --verbose

# 后台启动（生产用）
openclaw-cn gateway --port 18789 --daemon

# 查看状态
openclaw-cn status

# 查看日志
openclaw-cn logs

# 重启网关
openclaw-cn gateway restart

# 停止网关
openclaw-cn gateway stop

# ========== 技能相关 ==========
# 安装技能
openclaw-cn skill install <skill-name>

# 查看已安装技能
openclaw-cn skill list

# 移除技能
openclaw-cn skill remove <skill-name>

十、常见问题排查（别慌，都有救）

问题1：一键安装脚本报错

可能原因：

没有 curl 命令
权限不够
网络问题

解决方案：

# 安装 curl（如果缺失）
# macOS: 已自带，不用装
# Ubuntu/Debian:
sudo apt-get install curl

# CentOS/RHEL:
sudo yum install curl

# 使用 sudo 运行（如果权限不够）
curl -fsSL https://clawd.org.cn/install.sh | sudo bash

# 使用 wget 替代
wget -qO- https://clawd.org.cn/install.sh | bash

问题2：Node.js 版本过低

错误提示： Node version mismatch 或类似错误

原因： 你没仔细看教程，用了 Node 18 或更低版本

解决方案：

# 使用 nvm 升级
nvm install 22
nvm use 22

# 验证
node -v  # 应该输出 v22.x.x

问题3：npm 安装权限错误

错误提示： EACCES permission denied

原因： 你没有管理员权限

解决方案：

# 方案1：使用 sudo（简单粗暴）
sudo npm install -g openclaw-cn@latest

# 方案2：配置 npm 使用用户目录（推荐，不用 sudo）
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 然后重新安装
npm install -g openclaw-cn@latest

问题4：飞书收不到消息

检查清单：

✅ 飞书应用权限是否开启？
✅ 事件订阅是否配置？
✅ 机器人是否在群里？
✅ 配置文件中的 appId 和 appSecret 是否正确？
✅ 网关是否正常运行？

排查步骤：

# 查看日志
openclaw-cn logs | grep -i feishu

# 检查配置
cat ~/.openclaw/openclaw.json | grep -A 10 feishu

# 重启网关
openclaw-cn gateway restart

终极解决方案： 重启大法好（先试这个）

问题5：配置修改不生效

原因： 配置文件格式错误，或者忘记重启 OpenClaw

解决方案：

检查 JSON 格式是否正确（用 JSON Linter）
重启网关：

openclaw-cn gateway restart

问题6：提示 `command not found`

原因： openclaw-cn 未安装或未在 PATH 中

解决方案：

# 检查是否安装
which openclaw-cn

# 如果未找到，重新安装
npm install -g openclaw-cn@latest

# 如果已安装但仍找不到，检查 PATH
echo $PATH

# 手动添加到 PATH（如果需要）
export PATH=/usr/local/bin:$PATH

十一、进阶配置（别着急，先跑起来再说）

1. 配置多个 AI 模型

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "zai/glm-5",
        "fallbacks": ["anthropic/claude-3-5-sonnet-20241022", "openai/gpt-4"]
      },
      "models": {
        "zai/glm-5": {
          "alias": "GLM-5"
        },
        "anthropic/claude-3-5-sonnet-20241022": {
          "alias": "Claude-3.5-Sonnet"
        },
        "openai/gpt-4": {
          "alias": "GPT-4"
        }
      }
    }
  }
}

2. 配置工作区

工作区在 ~/.openclaw/workspace/，可以自定义：

SOUL.md — AI 的性格和行为准则（别写太奇怪的东西）
USER.md — 用户信息
MEMORY.md — 长期记忆
COMMANDS.md — 自定义命令

3. 安装技能

# 查看可用技能
openclaw-cn skill list

# 安装技能
openclaw-cn skill install github

十二、生产环境部署（如果你要 24/7 运行）

使用 PM2 守护进程

# 安装 PM2
npm install -g pm2

# 启动 OpenClaw
pm2 start "openclaw-cn gateway --port 18789" --name openclaw

# 开机自启
pm2 startup
pm2 save

# 查看日志
pm2 logs openclaw

# 监控
pm2 monit

使用 Systemd（Linux）

创建服务文件：

sudo nano /etc/systemd/system/openclaw.service

写入内容：

[Unit]
Description=OpenClaw-CN Gateway
After=network.target

[Service]
Type=simple
User=your-username
ExecStart=/usr/local/bin/openclaw-cn gateway --port 18789
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl enable openclaw
sudo systemctl start openclaw
sudo systemctl status openclaw

十三、安全最佳实践（别让你的 AI 被黑）

API 密钥管理

✅ 使用环境变量存储敏感信息
✅ 定期更换 API 密钥
❌ 不要把密钥提交到 Git 仓库
❌ 不要把密钥告诉你的前女友

网络安全

✅ 使用 HTTPS（Nginx/Caddy 反向代理）
✅ 配置防火墙，只开放必要端口
✅ 限制管理接口的访问 IP

访问控制

✅ 设置管理员白名单
✅ 定期审查访问日志
✅ 及时更新到最新版本

十四、社区和资源（遇到问题别自己死磕）

官方资源

官网： clawd.org.cn
文档： clawd.org.cn/docs
GitHub： github.com/jiulingyun/…
问题反馈： GitHub Issues

技能市场

ClawHub：各种现成的技能，拿来即用

结语：祝你好运

OpenClaw-CN 是个强大的工具，安装过程也很简单。如果你按照这个教程一步步来，应该能在 10 分钟内搞定。

推荐安装流程（记不住就收藏）：

# 最简单：一键安装
curl -fsSL https://clawd.org.cn/install.sh | bash

# 已有 Node.js：手动安装
npm install -g openclaw-cn@latest

# 初始化配置
openclaw-cn onboard --install-daemon

# 启动网关
openclaw-cn gateway --port 18789

# 开始使用！

OpenClaw 中文版安装全攻略：从零开始到完全搞定（不踩坑版）