OpenClaw 安装与配置教程

OpenClaw 是一款可私有部署的个人 AI 助手，运行在你自己的设备上，支持通过多种即时通讯工具（WhatsApp、Telegram、Slack、Discord、飞书等）进行交互。

一、环境要求

运行时环境：

• Node.js ≥ 22.16+（推荐 Node 24）
• npm ≥ 10
• 包管理器：推荐使用 pnpm（构建和安装更稳定）

支持平台：

• macOS
• Linux
• Windows

二、基础安装

方式一：npm 安装（通用）

npm install -g openclaw@latest

方式二：pnpm 安装（推荐）

pnpm add -g openclaw@latest

方式三：Bun 安装

bun install -g openclaw@latest

从源码安装（开发用途）

git clone https://github.com/openclaw/openclaw.git
cd openclaw

pnpm install
pnpm ui:build  # 首次运行自动安装 UI 依赖
pnpm build

# 开发模式（源码/配置变更自动重载）
pnpm gateway:watch

三、初始化配置

安装完成后，使用 Onboard 向导完成初始化：

openclaw onboard --install-daemon

该命令会：

• 引导你完成 Gateway 守护进程安装
• 配置工作空间（默认 ~/.openclaw/workspace）
• 设置 Channel 连接
• 安装必要的 Skills

--install-daemon 参数会将 Gateway 注册为系统服务（launchd/systemd），确保开机自启。

四、配置流程

---

个人觉得最方便的配置方法还得是交互式配置，只需要通过openclaw config或openclaw configure进行配置就好了

---

4.1 选择运行模式

OpenClaw 支持多种运行模式：

• 本地模式：Gateway 运行在本地，适合个人使用
• 远程模式：Gateway 运行在 Linux 服务器，通过 Tailscale 或 SSH 隧道访问

4.2 配置 AI 模型

编辑 ~/.openclaw/openclaw.json：

{
  "agent": {
    "model": "<provider>/<model-id>"
  }
}

支持的模型提供商：

• OpenAI（ChatGPT/Codex，需 OAuth 或 API Key）
• 其他主流大模型提供商

模型配置文档：

• 模型选择与认证：Models
• OAuth 与 API Key 轮换：Model Failover

4.3 认证配置

根据选择的渠道配置相应认证信息：

Telegram：

{
  "channels": {
    "telegram": {
      "botToken": "123456:ABCDEF"
    }
  }
}

Discord：

{
  "channels": {
    "discord": {
      "token": "你的 Bot Token"
    }
  }
}

Slack：
需要配置 SLACK_BOT_TOKEN 和 SLACK_APP_TOKEN 环境变量，或在配置文件中设置 channels.slack.botToken 和 channels.slack.appToken。

完整配置参考： Configuration Reference

五、常用命令

5.1 管理命令

# 启动 Gateway（指定端口和详细日志）
openclaw gateway --port 18789 --verbose

# 查看 Gateway 状态
openclaw gateway status

# 重启 Gateway
openclaw gateway restart

# 健康检查
openclaw doctor

# 更新 OpenClaw
openclaw update --channel stable|beta|dev

5.2 Agent 命令

# 发送消息给 Agent
openclaw agent --message "你的问题" --thinking high

# 列出活跃会话
openclaw sessions list

# 查看会话历史
openclaw sessions history --session <session-id>

5.3 Channel 命令

# 登录 Channel（如 WhatsApp、微信等）
openclaw channels login

# 登录指定 Channel
openclaw channels login --channel <channel-name>

# 发送消息
openclaw message send --to +1234567890 --message "Hello from OpenClaw"

5.4 Skill 命令

# 列出已安装 Skills
openclaw skills list

# 安装新 Skill
openclaw skills install <skill-name>

# 卸载 Skill
openclaw skills uninstall <skill-name>

5.5 聊天命令（在聊天窗口中使用）

在已连接的聊天渠道中发送：

• /status — 查看会话状态（模型、Token 消耗）
• /new 或 /reset — 重置会话
• /compact — 压缩会话上下文（生成摘要）
• /think <level> — 设置思考等级（off|minimal|low|medium|high|xhigh）
• /verbose on|off — 切换详细输出
• /usage off|tokens|full — 设置用量显示模式
• /restart — 重启 Gateway（群聊中仅群主可用）
• /activation mention|always — 群聊激活模式切换

六、守护进程配置

6.1 macOS（launchd）

onboard --install-daemon 会自动创建 launchd 服务。

手动管理：

# 查看服务状态
launchctl list | grep openclaw

# 停止服务
launchctl unload ~/Library/LaunchAgents/io.openclaw.gateway.plist

# 启动服务
launchctl load ~/Library/LaunchAgents/io.openclaw.gateway.plist

6.2 Linux（systemd）

onboard --install-daemon 会自动创建 systemd 用户服务。

手动管理：

# 查看服务状态
systemctl --user status openclaw-gateway

# 启动服务
systemctl --user start openclaw-gateway

# 停止服务
systemctl --user stop openclaw-gateway

# 开机自启
systemctl --user enable openclaw-gateway

# 查看日志
journalctl --user -u openclaw-gateway -f

6.3 后台进程模式

如果不使用守护进程，可使用后台运行：

# 使用 nohup
nohup openclaw gateway --port 18789 --verbose > openclaw.log 2>&1 &

# 使用 screen 或 tmux
screen -S openclaw
openclaw gateway --port 18789 --verbose
# Ctrl+A, D 退出 screen

后台进程文档： Background Process

七、配置文件位置

核心配置：

• 主配置文件：~/.openclaw/openclaw.json
• 凭证存储：~/.openclaw/credentials/
• 工作空间：~/.openclaw/workspace/（可配置）
• Skills 目录：~/.openclaw/workspace/skills/
• 日志文件：~/.openclaw/logs/

工作空间文件：

• AGENTS.md — Agent 行为协议
• SOUL.md — 人格设定
• IDENTITY.md — 身份标识
• USER.md — 用户信息
• TOOLS.md — 工具配置笔记

模板文件位置：

• 默认 AGENTS：AGENTS.default
• 各类模板：Templates

八、常见问题

Q1: Gateway 无法启动

检查项：

# 检查 Node.js 版本
node --version  # 应 ≥ 22.16

# 检查端口占用
lsof -i :18789

# 查看详细日志
openclaw gateway --verbose

Q2: Channel 连接失败

排查步骤：

1. 检查认证信息是否正确（Token、API Key）
2. 运行 openclaw doctor 检查配置
3. 查看渠道特定文档：Channels
4. 检查网络连通性（特别是 webhook 地址），并且是不能轻易去使用代理的，会导致请求不到

通用排查指南： Troubleshooting

Q3: 权限问题（macOS）

macOS 需要授予以下权限：

• 辅助功能（Accessibility）
• 屏幕录制（Screen Recording）
• 通知（Notifications）

权限管理： macOS Permissions

Q4: 模型调用失败

解决方案：

1. 检查模型配置是否正确
2. 验证 API Key 或 OAuth 状态
3. 配置模型故障转移：Model Failover
4. 查看用量跟踪：Usage Tracking

Q5: 浏览器工具无法使用（Linux）

Linux 需要安装 Chromium 依赖：

# Debian/Ubuntu
sudo apt-get install chromium-browser

# 或使用 OpenClaw 管理的浏览器
openclaw browser install

详细指南： Browser Troubleshooting

Q6: 如何更新 OpenClaw

# 更新到最新版
openclaw update

# 切换到 Beta 频道
openclaw update --channel beta

# 更新后检查
openclaw doctor

更新指南： Updating

Q7: DM 安全策略

默认情况下，陌生用户的私信会被拦截并返回配对码。

批准配对：

openclaw pairing approve <channel> <code>

开放私信（不推荐）：
在配置中设置 dmPolicy: "open" 并在 allowFrom 中包含 "*"。

安全指南： Security

---

快速开始（TL;DR）

# 1. 安装
pnpm add -g openclaw@latest

# 2. 初始化（含守护进程）
openclaw onboard --install-daemon

# 3. 启动 Gateway
openclaw gateway --port 18789 --verbose

# 4. 发送测试消息
openclaw message send --to +1234567890 --message "Hello from OpenClaw"

# 5. 与 Agent 对话
openclaw agent --message "Ship checklist" --thinking high

---

参考文档

• 官方文档索引
• 架构概览
• 配置参考
• 安全指南
• Onboard 向导
• 入门指南
• Discord 社区