【OpenClaw 】OpenClaw 安装与配置教程

OpenClaw 安装与配置教程

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

一、环境要求

运行时环境：

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

支持平台：

• macOS
• Linux
• Windows

二、基础安装

方式一：npm 安装（通用）

npminstall-gopenclaw@latest

方式二：pnpm 安装（推荐）

pnpmadd-gopenclaw@latest

方式三：Bun 安装

buninstall-gopenclaw@latest

从源码安装（开发用途）

gitclone https://github.com/openclaw/openclaw.gitcdopenclawpnpminstallpnpmui:build# 首次运行自动安装 UI 依赖pnpmbuild# 开发模式（源码/配置变更自动重载）pnpmgateway: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--port18789--verbose# 查看 Gateway 状态openclaw gateway status# 重启 Gatewayopenclaw gateway restart# 健康检查openclaw doctor# 更新 OpenClawopenclaw update--channelstable|beta|dev

5.2 Agent 命令

# 发送消息给 Agentopenclaw agent--message"你的问题"--thinkinghigh# 列出活跃会话openclaw sessions list# 查看会话历史openclaw sessionshistory--session<session-id>

5.3 Channel 命令

# 登录 Channel（如 WhatsApp、微信等）openclaw channels login# 登录指定 Channelopenclaw channels login--channel<channel-name># 发送消息openclaw message send--to+1234567890--message"Hello from OpenClaw"

5.4 Skill 命令

# 列出已安装 Skillsopenclaw skills list# 安装新 Skillopenclaw skillsinstall<skill-name># 卸载 Skillopenclaw 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|grepopenclaw# 停止服务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--userstatus openclaw-gateway# 启动服务systemctl--userstart openclaw-gateway# 停止服务systemctl--userstop openclaw-gateway# 开机自启systemctl--userenableopenclaw-gateway# 查看日志journalctl--user-uopenclaw-gateway-f

6.3 后台进程模式

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

# 使用 nohupnohupopenclaw gateway--port18789--verbose>openclaw.log2>&1&# 使用 screen 或 tmuxscreen-Sopenclaw openclaw gateway--port18789--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/Ubuntusudoapt-getinstallchromium-browser# 或使用 OpenClaw 管理的浏览器openclaw browserinstall

详细指南：Browser Troubleshooting

Q6: 如何更新 OpenClaw

# 更新到最新版openclaw update# 切换到 Beta 频道openclaw update--channelbeta# 更新后检查openclaw doctor

更新指南：Updating

Q7: DM 安全策略

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

批准配对：

openclaw pairing approve<channel><code>

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

安全指南：Security

快速开始（TL;DR）

# 1. 安装pnpmadd-gopenclaw@latest# 2. 初始化（含守护进程）openclaw onboard --install-daemon# 3. 启动 Gatewayopenclaw gateway--port18789--verbose# 4. 发送测试消息openclaw message send--to+1234567890--message"Hello from OpenClaw"# 5. 与 Agent 对话openclaw agent--message"Ship checklist"--thinkinghigh

参考文档

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