以观书法
108.85M · 2026-02-05
OpenClaw 是一个运行在本地设备上的个人 AI 助手。它可以在您已经使用的渠道上回复您（WhatsApp、T@elegrimm、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、WebChat），以及 BlueBubbles、Matrix、Zalo 和 Zalo Personal 等扩展渠道。它可以在 macOS/iOS/Android 上进行语音对话，并可以渲染您控制的实时 Canvas。Gateway 只是控制平面——产品本身才是助手。
OpenClaw 的核心特点：
| 组件 | 要求 |
|---|---|
| 操作系统 | Ubuntu 20.04 LTS 或更高版本 |
| Node.js | ≥ 22.0.0（必需） |
| 内存 | 至少 4GB RAM（建议 8GB） |
| 存储 | 至少 2GB 可用空间 |
| 网络 | 稳定的互联网连接 |
在安装 OpenClaw 之前，请确保您的系统已安装 Node.js ≥ 22：
# 检查 Node.js 版本
node --version
# 如果版本低于 22，请先安装或升级 Node.js
# 使用 nvm 安装（推荐）
curl -o- | bash
source ~/.bashrc
nvm install 22
nvm use 22
OpenClaw 支持以下包管理器：
# 全局安装 OpenClaw
npm install -g openclaw@latest
# 验证安装
openclaw --version
# 全局安装 OpenClaw
pnpm add -g openclaw@latest
# 验证安装
openclaw --version
如果您需要最新开发版本或想要贡献代码：
# 克隆仓库
git clone
cd openclaw
# 安装依赖（推荐使用 pnpm）
pnpm install
# 构建项目
pnpm build
# 运行 onboarding 向导
pnpm openclaw onboard --install-daemon
安装完成后，运行以下命令验证安装：
# 查看 OpenClaw 版本
openclaw --version
# 查看帮助信息
openclaw --help
OpenClaw 提供了一个交互式的配置向导，帮助您完成初始设置：
# 启动配置向导并安装守护进程
openclaw onboard --install-daemon
配置向导会引导您完成以下步骤：
OpenClaw Onboarding Wizard
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. 配置模型 (anthropic/claude-opus-4-5)
2. 配置工作区 (~/.openclaw/workspace)
3. 配置通道 (WhatsApp/T@elegrimm/Slack/Discord)
4. 安装 Gateway 守护进程
5. 完成
OpenClaw 支持多种 AI 模型，官方推荐：
配置示例（~/.openclaw/openclaw.json）：
{
agent: {
model: "anthropic/claude-opus-4-5",
},
}
工作区是 OpenClaw 存储配置和文件的地方：
~/.openclaw/workspaceAGENTS.md, SOUL.md, TOOLS.mdOpenClaw 支持多种消息平台：
| 平台 | 配置方式 |
|---|---|
pnpm openclaw channels login | |
| T@elegrimm | 设置 TELEGRAM_BOT_TOKEN |
| Slack | 设置 SLACK_BOT_TOKEN + SLACK_APP_TOKEN |
| Discord | 设置 DISCORD_BOT_TOKEN |
| Signal | 需要 signal-cli |
| iMessage | 通过 BlueBubbles 推荐 |
守护进程确保 Gateway 在后台持续运行：
# 安装守护进程
openclaw onboard --install-daemon
# 手动启动 Gateway
openclaw gateway --port 18789 --verbose
配置完成后，启动 Gateway：
# 前台运行
openclaw gateway --port 18789 --verbose
# 或使用后台模式
openclaw gateway --port 18789
Gateway 默认：ws://127.0.0.1:18789
# 启动 Gateway
openclaw gateway --port 18789 --verbose
# 停止 Gateway（按 Ctrl+C）
# 或使用守护进程管理
openclaw gateway stop
# 检查 Gateway 状态
openclaw doctor
# 发送消息到指定联系人
openclaw message send --to +1234567890 --message "Hello from OpenClaw"
# 发送消息到群组
openclaw message send --channel telegram --message "Hello group!"
# 发送消息给助手
openclaw agent --message "Ship checklist" --thinking high
# 交互式对话模式
openclaw agent
# 登录通道
pnpm openclaw channels login
# 查看已配置的通道
openclaw channels list
# 查看通道状态
openclaw doctor
# 运行系统诊断
openclaw doctor
# 检查配置
openclaw doctor --config
# 查看日志
openclaw doctor --logs
# 更新到最新版本
openclaw update
# 切换更新通道
openclaw update --channel stable|beta|dev
# 更新通道说明
# - stable: 稳定版（推荐）
# - beta: 测试版
# - dev: 开发版
# 查看帮助
openclaw --help
# 查看特定命令帮助
openclaw gateway --help
openclaw agent --help
openclaw message --help
# 配对管理
openclaw pairing approve <channel> <code>
问题：Node.js version must be >= 22
解决方案：
# 检查当前版本
node --version
# 使用 nvm 安装 Node.js 22
curl -o- | bash
source ~/.bashrc
nvm install 22
nvm use 22
问题：Port 18789 already in use 或 Gateway 连接失败
解决方案：
# 检查端口占用
lsof -i :18789
# 停止占用端口的进程
kill <PID>
# 或使用其他端口
openclaw gateway --port 18790
问题：EACCES: permission denied
解决方案：
# 方法 1：使用 sudo（不推荐）
sudo npm install -g openclaw@latest
# 方法 2：配置 npm 使用用户目录
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw@latest
问题：WhatsApp/T@elegrimm 等通道无法登录
解决方案：
# 检查凭证配置
cat ~/.openclaw/openclaw.json
# 检查通道日志
openclaw doctor --logs
# 重新登录通道
pnpm openclaw channels login
问题：Gateway 守护进程无法启动或停止工作
解决方案：
# 检查守护进程状态
systemctl --user status openclaw
# 重新安装守护进程
openclaw onboard --install-daemon
# 手动启动守护进程
systemctl --user start openclaw
# 查看守护进程日志
journalctl --user -u openclaw -f
问题：Gateway 运行一段时间后崩溃
解决方案：
# 检查内存使用
free -h
# 清理 Gateway 进程
openclaw gateway stop
pkill -f openclaw
# 重启 Gateway
openclaw gateway --port 18789
当遇到问题时，运行以下命令获取诊断信息：
# 完整系统检查
openclaw doctor
# 检查配置
openclaw doctor --config
# 检查通道状态
openclaw doctor --channels
# 检查日志
openclaw doctor --logs
# 检查网络连接
openclaw doctor --network
OpenClaw 的日志文件位置：
# Gateway 日志
cat ~/.openclaw/logs/gateway.log
# 通道日志
cat ~/.openclaw/logs/channels.log
# 实时查看日志
tail -f ~/.openclaw/logs/gateway.log
如果以上方法都无法解决您的问题：
┌─────────────────────────────────────────────────────────────────┐
│ OpenClaw 架构图 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ WhatsApp / T@elegrimm / Slack / Discord / Google Chat / Signal │
│ iMessage / BlueBubbles / Microsoft Teams / Matrix / Zalo │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Gateway (控制平面) │ │
│ │ ws://127.0.0.1:18789 │ │
│ │ • 会话管理 • 通道连接 • 工具执行 • 事件处理 │ │
│ └────────────────────────┬────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Pi Agent │ │ CLI │ │ Web UI │ │
│ │ (RPC) │ │ openclaw.. │ │ Dashboard │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ macOS App │ │ iOS Node │ │ Android Node│ │
│ │ Menu Bar │ │ Canvas │ │ Canvas │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
$ openclaw onboard --install-daemon
OpenClaw Onboarding Wizard
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. 配置模型 (anthropic/claude-opus-4-5)
2. 配置工作区 (~/.openclaw/workspace)
3. 配置通道 (WhatsApp/T@elegrimm/Slack/Discord)
4. 安装 Gateway 守护进程
5. 完成
> 选择操作: 4
正在安装 Gateway 守护进程...
守护进程安装成功！
$ openclaw gateway --port 18789 --verbose
Gateway 启动在 ws://127.0.0.1:18789
Gateway 已就绪
$ openclaw message send --to +1234567890 --message "Hello from OpenClaw"
消息已发送
$ openclaw agent --message "Ship checklist" --thinking high
正在思考...
响应已生成
完成安装后，建议您：
openclaw onboard 完成初始配置openclaw gateway --port 18789 --verboseHappy Exfoliating!
OpenClaw 由 Peter Steinberger 和社区开发维护
