OpenClaw 完全指南：打造你的个人 AI Agent

OpenClaw 的核心理念：让 AI 成为真正能接入你生活和工作流的长期助手，不是每次都要从零开始的工具。

一、认识 OpenClaw

1.1 什么是 OpenClaw？

OpenClaw（原名 Clawdbot）是 2026 年现象级开源 AI Agent 项目，核心思想是把 AI 大模型（大脑）+ 本地工具（手脚）+ 聊天软件（嘴巴耳朵） 连接起来，让 AI 真正成为你的电脑管家。

官方资源：

• GitHub：https://github.com/openclaw/openclaw
• 官方文档：https://docs.openclaw.ai
• 社区：https://discord.com/invite/clawd
• 技能市场：https://clawhub.ai

1.2 核心特点

1.3 OpenClaw vs Hermes Agent

二、安装部署

2.1 系统要求

2.2 一键安装（macOS / Linux）

curl -fsSL https://get.openclaw.ai | sh

2.3 手动安装

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖
npm install

# 全局安装 CLI
npm install -g openclaw

2.4 Docker 部署（云服务器）

# 拉取镜像
docker pull openclaw/openclaw:latest

# 运行容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

2.5 启动 Gateway

# 启动主服务
openclaw gateway start

# 检查状态
openclaw status

# 查看日志
openclaw logs

三、配置目录结构

OpenClaw 的配置都在 ~/.openclaw/ 目录下：

~/.openclaw/
├── openclaw.json          # 主配置文件（JSON/JSON5）
├── workspace/             # AI "灵魂"文件夹（推荐 git 版本控制）
│   ├── SOUL.md          # 人格设定（语气、风格、三观）
│   ├── USER.md          # 你的个人信息
│   ├── MEMORY.md        # 长期记忆（可手动编辑）
│   ├── IDENTITY.md      # Agent 名称、形象、emoji
│   ├── AGENTS.md        # 多 Agent 路由规则
│   ├── HEARTBEAT.md     # 定时自动检查机制
│   ├── BOOTSTRAP.md     # 首次启动引导脚本（一次性）
│   ├── TOOLS.md         # 环境配置（服务器 IP、摄像头名等）
│   └── memory/          # 每日日志目录
│       ├── 2026-04-25.md
│       └── 2026-04-24.md
├── extensions/           # 插件扩展目录
├── skills/              # Skills 技能目录
└── sessions/           # 会话记录

四、核心配置文件详解

4.1 SOUL.md — 灵魂（人格设定）

定义 Agent 的身份、语气、风格、行为原则。Agent 可以修改此文件。

# SOUL.md

你是米粒，军哥的 AI 私人助手。形象是一只赛博黑猫 🐈‍⬛。

## 性格
- 聪明、高效、有点话多
- 偶尔毒舌但从不恶意
- 对技术充满好奇
- 主动但不越界

## 说话风格
- 简洁直接，不啰嗦
- 可以用 emoji，但克制
- 技术术语保留英文
- 重要信息用加粗标注

## 行为准则
- 能帮忙做的事就直接做，不反复确认
- 不确定的事先问再做
- 涉及发送外部消息，必须确认
- 深夜（23:00-08:00）除非紧急否则不主动打扰

4.2 IDENTITY.md — 身份（外部形象）

定义 Agent 对外的展示信息：

# IDENTITY.md

- **Name:** 米粒
- **Creature:** AI 助手
- **Vibe:** 简洁、高效、温柔
- **Emoji:** 🌸
- **Avatar:**

4.3 USER.md — 用户信息

记录用户的偏好和背景，让 AI 更懂你：

# USER.md

- **Name:** 军哥
- **Timezone:** Asia/Shanghai
- **Location:** 河北保定
- **Occupation:** 高级软件工程师

4.4 AGENTS.md — 多 Agent 路由规则

定义多 Agent 的工作模式和路由规则。Agent 只能读，不能写。

# AGENTS.md

## 子 Agent 配置
- 当需要执行代码时 → 启动 coding-agent
- 当需要搜索时 → 使用 web_search
- 当需要发邮件时 → 调用邮件技能

## 启动规则
1. 每次新会话先读 SOUL.md、USER.md
2. 私聊飞书额外读 memory/ 日志
3. 运行 openclaw status 检查网关状态

## 行为规则
- 默认主会话处理所有请求
- 复杂任务可 spawn 子 agent
- 群聊规范：参与不主导

4.5 HEARTBEAT.md — 心跳机制

心跳让 AI 从「被动工具」变成「主动助手」。按设定的时间间隔自动执行检查：

# HEARTBEAT.md

## 定期检查（每次 heartbeat）
1. 检查是否有待办任务
2. 看看有没有重要消息
3. 主动思考：检查项目进展，给用户有价值的建议

**触发条件：**
- 距离上次用户消息超过 10 分钟
- 非深夜（23:00-08:00）

**表达方式：**
- 每次只说 1 件事
- 保持自然，像朋友聊天

4.6 MEMORY.md — 长期记忆

沉淀精华知识，蒸馏后的核心记忆。Agent 可以修改。

# MEMORY.md — 长期记忆

## 项目进度
| 项目 | 状态 |
|------|------|
| aigc-studio | 进行中 |

## 服务器
- 主服务器：39.104.51.106 / root / [密码已存储]

## 技能清单
- 公众号发布 baoyu-post-to-wechat
- PPT 生成 ppt-nano-master
- 天气查询 weather

4.7 TOOLS.md — 环境配置

存储环境特定的配置信息：

# TOOLS.md

## 服务器
- 主服务器: 39.104.51.106 / root / [密码]

## 项目目录
- 主项目目录: /Volumes/MANIC/Project
- 次项目目录: /Users/gu/Documents/Project

五、多平台接入

5.1 飞书接入（官方插件）

步骤一：创建飞书应用

1. 前往 飞书开放平台
2. 创建企业自建应用，获取 App ID 和 App Secret
3. 添加「机器人」能力

步骤二：开启必要权限

步骤三：配置 OpenClaw

# 添加飞书渠道
openclaw channel add feishu

# 配置 App ID 和 Secret
openclaw config set channels.feishu.app_id your-app-id
openclaw config set channels.feishu.app_secret your-app-secret

# 开启流式响应（打字机效果，可选）
openclaw config set channels.feishu.streaming true

# 重启服务
openclaw gateway restart

步骤四：配置 Webhook

在飞书开放平台配置事件订阅：

• 请求地址：https://你的域名/feishu/webhook
• 订阅事件：im.message.receive_v1

5.2 Telegram 接入

# 获取 Bot Token（找 @BotFather 获取）
openclaw config set channels.telegram.bot_token your-bot-token

# 添加频道
openclaw channel add telegram

# 重启
openclaw gateway restart

5.3 Discord 接入

openclaw config set channels.discord.bot_token your-discord-bot-token
openclaw config set channels.discord.guild_id your-guild-id
openclaw channel add discord

六、Skills 技能系统

6.1 什么是 Skills？

Skills 是 OpenClaw 的插件系统，像 npm 包一样可以安装、分享、管理。每个 Skill 是一个包含 SKILL.md 的文件夹。

6.2 安装 Skills

# 从 ClawHub 安装
openclaw skills install clawhub/wechat-publisher

# 查看已安装
openclaw skills list

# 更新
openclaw skills update

# 卸载
openclaw skills uninstall clawhub/wechat-publisher

6.3 ClawHub 常用 Skills

6.4 手动编写 Skill

创建 ~/.openclaw/skills/my-skill/SKILL.md：

# 我的自定义技能

## 触发词
当用户说「做什么」时触发

## 描述
这个技能帮助完成 xxx 任务

## 使用方法
运行相关命令

## 环境要求
需要安装 xxx 工具

七、多 Agent 协作

7.1 子 Agent 使用场景

• 复杂编码任务 → 启动 coding-agent
• 搜索研究 → 启动 search-agent
• 长文档处理 → 启动 doc-agent

7.2 配置 AGENTS.md

# AGENTS.md

## 路由规则
| 任务类型 | 启动 Agent |
|---------|-----------|
| 写代码 / 调试 | coding-agent |
| 网页搜索 / 研究 | search-agent |
| PDF/Word 处理 | doc-agent |
| 默认 | 主会话处理 |

## 启动参数
- coding-agent: 使用 --permission-mode bypassPermissions
- search-agent: 使用 medium context

7.3 派发任务

在对话中直接说：「帮我写一个 xxx → 这会派发给 coding-agent」

八、心跳机制详解

8.1 心跳原理

Heartbeat 是 AI 的「循环任务调度器」，按设定间隔自动触发 AI 执行检查。

8.2 配置频率

# 查看当前心跳间隔
openclaw config get heartbeat.interval

# 设置为 5 分钟（默认）
openclaw config set heartbeat.interval 5m

# 设置为 10 分钟
openclaw config set heartbeat.interval 10m

# 关闭心跳
openclaw config set heartbeat.enabled false

8.3 HEARTBEAT.md 模板

# HEARTBEAT.md

## 每次检查内容
1. 检查邮件（新消息？）
2. 查看日历（2小时内有会议？）
3. 推送有价值的信息给用户

## 何时打扰
- 有重要邮件
- 日历事件 < 2 小时
- > 8 小时没说话

## 何时安静
- 深夜（23:00-08:00）
- 用户明显在忙
- 刚检查完 < 30 分钟

九、安全配置

9.1 飞书 Channel 配置

# ~/.openclaw/openclaw.json
{
  "channels": {
    "feishu": {
      "app_id": "your-app-id",
      "app_secret": "your-secret",
      "verification_token": "your-token",
      "encrypt_key": "your-encrypt-key"
    }
  }
}

9.2 禁止命令白名单

# 禁止某些危险命令
openclaw config set security.deny_commands ["rm -rf", "dd if="]

# 开启操作确认
openclaw config set security.confirm_destructive true

9.3 API 密钥安全

敏感信息不要写在配置文件里，使用环境变量：

export OPENCLAW_DEEPSEEK_API_KEY=sk-xxxx
openclaw config set model.api_key_from_env OPENCLAW_DEEPSEEK_API_KEY

十、常见问题排查

Q1: Gateway 启动失败

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

# 查看详细错误
openclaw logs --verbose

# 重新初始化
openclaw init --force

Q2: 飞书收不到消息

1. 检查飞书应用是否已发布
2. 确认 Webhook URL 可公网访问
3. 检查权限是否都开启了
4. 查看日志：openclaw logs --channel feishu

Q3: AI 回复很慢

# 切换更快模型
openclaw config set model.provider openai
openclaw config set model.name gpt-4o-mini

# 检查网络延迟
openclaw model ping

Q4: 记忆不生效

# 检查 MEMORY.md 是否存在
cat ~/.openclaw/workspace/MEMORY.md

# 手动添加记忆
openclaw memory add "用户偏好使用 DeepSeek 模型"

Q5: Skills 安装失败

# 检查网络
curl https://clawhub.ai

# 使用代理
export HTTPS_PROXY=http://127.0.0.1:7890
openclaw skills install clawhub/xxx

结语

OpenClaw 代表了一种新的 AI 使用范式——不是每次都要从零开始的聊天工具，而是能真正融入你的工作流、记住你的习惯、主动帮你思考的数字伙伴。

配合飞书等消息平台，OpenClaw 可以成为你全天候的私人助理——处理信息、完成任务、管理日程、记住你说过的一切。

相关资源：

• GitHub：https://github.com/openclaw/openclaw
• 官方文档：https://docs.openclaw.ai
• 社区 Discord：https://discord.com/invite/clawd
• 技能市场：https://clawhub.ai