近几个月，「AI Agent」成为技术圈的高频词，但大多数人停留在 Demo、插件和概念层。 真正能跑在本地 / 服务器、拥有真实权限、能持续执行任务的 Agent 并不多。
OpenClaw，正是目前少数几个工程完整、可部署、可二次开发的开源 AI Agent 框架之一。
本文专注于实际部署流程与避坑指南。
一、OpenClaw 到底是什么？先说清楚定位
一句话说明白：
OpenClaw 是一个可部署在本地或服务器上的开源 AI Agent 框架，具备 Gateway（通信）、Dashboard（控制台）和 Skills（能力插件）三大核心模块。
和 ChatGPT / 插件的本质区别在于：
| 对比项 | 普通 AI 工具 | OpenClaw |
|---|---|---|
| 运行位置 | 云端 | 本地 / VPS |
| 权限 | 受限 | 可控高权限 |
| 持久运行 | 否 | 是 |
| 自动执行 | 弱 | 强 |
| 可二开 | 几乎不可 | 完全可 |
所以 OpenClaw 不是'聊天机器人'，而是一个真正意义上的 AI 执行体。
二、为什么一定要'认真搭'？
很多人第一次部署失败，不是技术不行，而是没搞清楚它的危险边界。
OpenClaw 具备的能力包括但不限于：
- 读写本地文件
- 调用系统命令
- 请求外部 API
- 长时间后台运行
- 通过 Gateway 接入 Telegram / Discord 等
👉 这意味着它是'高权限 Agent'
所以： ❌ 不建议直接装在日常办公电脑 ✅ 强烈建议：独立 VPS / Docker / 隔离环境
三、部署环境选择（这一段决定你后面顺不顺）
推荐配置（实战可用）
- 系统：Ubuntu 20.04 / 22.04
- CPU：2 核起步（4 核更稳）
- 内存：4GB 起步（8GB 更舒服）
- 用途：只跑 OpenClaw，不混别的服务
Windows 支持，但 Linux 更稳定通用
四、基础环境准备（一步都不能省）
1️⃣ 更新系统 & 基础工具
sudo apt update
sudo apt install -y git curl unzip
2️⃣ 安装 Node.js（OpenClaw 必需）
官方要求 Node 18+，推荐用 nvm：
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18
验证：
node -v
npm -v
3️⃣（可选但推荐）安装 pnpm
源码部署 & 二开基本都用它：
npm install -g pnpm
五、安装 OpenClaw（两种方式，选一种）
方式一：CLI 全局安装（最快）
适合：
- 想快速跑起来
- 不改源码
npm install -g openclaw
验证：
openclaw --version
看到版本号，说明 CLI 安装成功。
方式二：源码部署（进阶 / 二开）
适合：
- 想改 UI
- 想接自己系统
- 想写自定义 skills
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
六、最关键一步：Onboard 初始化（很多人卡死在这）
OpenClaw 不是装完就能用，必须执行 onboarding。
CLI 安装方式：
openclaw onboard --install-daemon
源码方式：
pnpm openclaw onboard --install-daemon
这个步骤会做几件事：
- 初始化 Gateway
- 生成本地配置
- 注册运行服务（daemon）
- 绑定 Dashboard
- 创建 Agent 身份
👉 90% 的问题，都发生在'没正确 onboard'
七、检查 Gateway 是否正常运行
openclaw gateway status
正常情况下你会看到：
- running
- healthy
- listening on port xxx
如果不是，直接看日志：
openclaw gateway logs
八、启动 Dashboard（这是你管理的关键）
openclaw dashboard
你将看到：
- Agent 状态
- 会话记录
- Skills 管理
- Gateway 连接情况
- 系统日志
九、Skills（能力插件）怎么理解？
你可以把 Skills 理解成：
AI 能调用的'函数 + 权限集合'
比如：
- 查询区块链数据
- 调用内部 API
- 执行脚本
- 发送 Telegram 消息
- 读取服务器状态
新手建议顺序：
- 只读类 skills
- 通知 / 查询类
- 再考虑执行型
不要一上来给它 root 权限
十、最常见 6 个坑
❌ 1. Gateway 起不来
- Node 版本不对
- 端口被占用
- 没 onboard 完
❌ 2. Dashboard 打不开
- 防火墙没放端口
- 服务器没映射
- 服务未运行
❌ 3. Skill 不生效
- 权限没授权
- 配置未 reload
- 写法不符合 schema
❌ 4. Agent 行为不可控
- skills 权限过大
- prompt 未限制
- 没做沙箱
❌ 5. 一直报错但不知道为什么
- 不看 gateway logs
- 不看 dashboard logs
❌ 6. 直接装在生产服务器
- 这是最危险的
十一、什么叫'搭建成功'？（验收标准）
满足以下 5 条，即可视为部署完成：
✅ CLI 正常
✅ Gateway running
✅ Dashboard 可访问
✅ 能启用至少 1 个 skill
✅ Agent 能完成一次完整任务
