夜雨聆风一篇搞定 OpenClaw 的安装、启动、配置与目录结构详解
一、OpenClaw 是什么？
OpenClaw 是一个自托管的 AI 网关服务，它能够将你常用的聊天应用（WhatsApp、Telegram、Discord、飞书、iMessage 等）连接到 AI 编程智能体。简单来说，你只需要在自己的设备上运行一个 Gateway 进程，就可以通过手机上的聊天软件随时随地调用 AI 助手。
核心特点：
- • 自托管：数据完全由你自己掌控，不依赖第三方云服务
- • 多渠道支持：一个 Gateway 同时服务 WhatsApp、Telegram、Discord、飞书等多个平台
- • 智能体原生：专为编程智能体设计，支持工具调用、会话管理、记忆系统
- • 开源免费：MIT 许可证，社区驱动开发
二、系统要求
在开始安装之前，请确保你的系统满足以下要求：
| 项目 | 要求 |
|---|---|
| 操作系统 | macOS / Linux / Windows (推荐 WSL2) |
| Node.js | 版本 22 或更高 |
| 包管理器 | npm / pnpm / bun（任选其一） |
检查 Node 版本：
node --version
# 输出应显示 v22.x.x 或更高三、安装方式详解
OpenClaw 提供多种安装方式，推荐使用安装脚本一键完成。
3.1 方式一：安装脚本（推荐）
这是最简单的安装方式，脚本会自动检测并安装 Node.js，然后完成 OpenClaw 的安装。
macOS / Linux / WSL2：
curl -fsSL https://openclaw.ai/install.sh | bashWindows PowerShell：
iwr -useb https://openclaw.ai/install.ps1 | iex安装完成后，脚本会自动启动配置向导。
3.2 方式二：npm 全局安装
如果你已经安装了 Node.js 22+，可以直接使用 npm 安装：
npm install -g openclaw@latest如果遇到 sharp 构建错误，可以使用以下命令：
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest3.3 方式三：pnpm 安装
pnpm 用户需要额外的构建脚本审批步骤：
pnpm add -g openclaw@latest
pnpm approve-builds -g # 审批 openclaw、sharp 等包的构建脚本3.4 方式四：从源码构建
开发者或贡献者可以选择从源码构建：
# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw
# 安装依赖并构建
pnpm install
pnpm ui:build
pnpm build
# 全局链接 CLI
pnpm link --global四、启动命令详解
安装完成后，你需要运行初始化配置和启动服务。
4.1 运行配置向导
openclaw onboard --install-daemon这个命令会：
- 1. 启动交互式配置向导
- 2. 引导你设置 API 认证
- 3. 配置 Gateway 参数
- 4. 安装系统服务（launchd/systemd）
4.2 启动 Gateway 服务
方式一：后台服务模式
openclaw gateway start方式二：前台运行模式
openclaw gateway --port 18789前台模式适合调试和故障排查，日志会直接输出到终端。
4.3 查看服务状态
openclaw gateway status输出示例：
Gateway Service: running (pid: 12345)
WebSocket: ws://127.0.0.1:18789
Config: ~/.openclaw/openclaw.json4.4 打开控制面板
openclaw dashboard这会在浏览器中打开 Web 控制界面（默认地址：http://127.0.0.1:18789/）。
五、常用命令速查表
以下是 OpenClaw 最常用的命令汇总：
| 命令 | 功能说明 |
|---|---|
openclaw onboard | 启动配置向导 |
openclaw gateway start | 启动 Gateway 服务 |
openclaw gateway stop | 停止 Gateway 服务 |
openclaw gateway restart | 重启 Gateway 服务 |
openclaw gateway status | 查看服务状态 |
openclaw gateway --port 18789 | 前台运行 Gateway |
openclaw dashboard | 打开 Web 控制界面 |
openclaw doctor | 诊断配置问题 |
openclaw status | 查看会话和连接状态 |
openclaw config get <path> | 获取配置值 |
openclaw config set <path> <value> | 设置配置值 |
openclaw channels list | 列出已配置的渠道 |
openclaw channels login | 登录渠道账号（如 WhatsApp） |
openclaw logs --follow | 实时查看日志 |
openclaw models status | 查看模型配置状态 |
六、目录结构详解
OpenClaw 的核心数据存储在 ~/.openclaw/ 目录下，了解每个文件的作用有助于更好地管理和调试。
~/.openclaw/
├── openclaw.json # 主配置文件（JSON5 格式）
├── openclaw.json.bak # 配置文件备份
├── workspace/ # 智能体工作空间
│ ├── AGENTS.md # 工作空间说明文档
│ ├── SOUL.md # 智能体人格定义
│ ├── USER.md # 用户信息
│ ├── MEMORY.md # 长期记忆文件
│ ├── HEARTBEAT.md # 心跳检查配置
│ ├── TOOLS.md # 工具配置说明
│ ├── IDENTITY.md # 身份标识
│ └── memory/ # 每日记忆日志
│ └── YYYY-MM-DD.md # 按日期存储的记忆文件
├── agents/ # 多智能体配置目录
├── channels/ # 渠道会话数据
├── devices/ # 设备配对信息
├── logs/ # 日志文件目录
├── media/ # 媒体文件缓存
├── cron/ # 定时任务配置
├── delivery-queue/ # 消息投递队列
├── identity/ # 身份凭证
├── subagents/ # 子智能体数据
└── extensions/ # 扩展插件6.1 核心文件说明
openclaw.json - 主配置文件
这是 OpenClaw 的核心配置文件，采用 JSON5 格式（支持注释和尾逗号）。基本结构：
{
// Gateway 网关配置
gateway: {
port: 18789, // WebSocket 端口
mode: "local", // 运行模式：local | remote
auth: {
mode: "token", // 认证方式：token | password
token: "your-token" // 认证令牌
}
},
// 智能体默认配置
agents: {
defaults: {
workspace: "~/.openclaw/workspace",
model: {
primary: "anthropic/claude-sonnet-4-5"
}
}
},
// 渠道配置
channels: {
whatsapp: {
enabled: true,
dmPolicy: "pairing", // DM 访问策略
allowFrom: ["+15555550123"]
},
telegram: {
enabled: true,
botToken: "123:abc"
}
}
}workspace/ - 智能体工作空间
这是 AI 智能体的"大脑"所在，包含：
- • SOUL.md：定义智能体的人格、语气和行为准则
- • USER.md：存储用户的基本信息和偏好
- • MEMORY.md：长期记忆，保存重要决策和上下文
- • memory/ 目录：每日记忆日志，记录当天发生的事件
AGENTS.md - 工作空间指南
这个文件告诉智能体如何使用工作空间：
- • 每次会话开始时，智能体会自动读取 SOUL.md、USER.md 和当天的记忆文件
- • 记忆文件帮助智能体保持上下文连续性
七、配置示例
7.1 最小配置
// ~/.openclaw/openclaw.json
{
agents: {
defaults: {
workspace: "~/.openclaw/workspace"
}
},
channels: {
whatsapp: {
allowFrom: ["+15555550123"]
}
}
}7.2 多渠道配置
{
channels: {
whatsapp: {
enabled: true,
dmPolicy: "pairing",
groups: {
"*": { requireMention: true }
}
},
telegram: {
enabled: true,
botToken: "123456:ABC-DEF",
dmPolicy: "allowlist",
allowFrom: ["tg:12345678"]
},
discord: {
enabled: true,
botToken: "MTk4NjI...",
dmPolicy: "open"
}
}
}7.3 模型配置
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-5",
fallbacks: ["openai/gpt-4o"]
}
}
}
}八、故障排查
8.1 常见问题诊断
# 运行诊断工具
openclaw doctor
# 查看详细日志
openclaw logs --follow
# 检查配置有效性
openclaw config validate8.2 openclaw 命令找不到
如果安装后运行 openclaw 提示命令不存在：
# 检查 npm 全局路径
npm prefix -g
# 添加到 PATH（添加到 ~/.zshrc 或 ~/.bashrc）
export PATH="$(npm prefix -g)/bin:$PATH"8.3 Gateway 无法启动
检查端口是否被占用：
# macOS/Linux
lsof -i :18789
# 终止占用进程或使用其他端口
openclaw gateway --port 18790九、进阶功能
9.1 心跳检查
设置定期检查任务：
{
agents: {
defaults: {
heartbeat: {
every: "30m", // 每 30 分钟
target: "last" // 发送到上次对话的渠道
}
}
}
}9.2 定时任务（Cron）
{
cron: {
enabled: true,
maxConcurrentRuns: 2
}
}9.3 沙箱模式
在隔离的 Docker 容器中运行智能体：
{
agents: {
defaults: {
sandbox: {
mode: "non-main", // off | non-main | all
scope: "agent" // session | agent | shared
}
}
}
}十、更新与卸载
10.1 更新 OpenClaw
openclaw update
# 或
npm update -g openclaw10.2 卸载
# 卸载服务
openclaw uninstall --service --state
# 卸载 CLI
npm uninstall -g openclaw
# 完全清理
openclaw uninstall --all --yes结语
OpenClaw 为开发者和高级用户提供了一个强大的自托管 AI 助理解决方案。通过本文的详细指南，你应该已经掌握了从安装到配置的完整流程。接下来，你可以：
- 1. 连接你常用的聊天渠道
- 2. 自定义智能体的人格和记忆
- 3. 探索更多高级功能（多智能体、沙箱、自动化等）
开始打造属于你自己的私人 AI 助理吧！ 🦞
