夜雨聆风从入门到高手
一份关注实用操作的 OpenClaw 使用手册，涵盖会话管理、技能开发、Agent 使用和常用命令。
一、核心概念速览
OpenClaw 本质上是一个 AI Agent 运行时，它把大模型、工具调用、多渠道通信整合在一起。几个关键概念：
| Gateway | |
| Agent | |
| Session | |
| Channel | |
| Skill | |
| Workspace |
核心架构：用户通过 Channel 发消息 → Gateway 接收并路由 → Agent 处理（调用模型+工具）→ 结果返回 Channel。
二、安装与初始化
2.1 安装
npm install -g openclaw
2.2 初始化配置
openclaw setup
这会创建 ~/.openclaw/openclaw.json 配置文件和 Agent 工作区。
2.3 工作区文件结构
~/.openclaw/workspace/
├── AGENTS.md # Agent 行为指令（必读）
├── SOUL.md # 人格定义（语气、边界）
├── USER.md # 用户档案
├── IDENTITY.md # Agent 身份（名字、emoji）
├── TOOLS.md # 本地工具备注
├── MEMORY.md # 长期记忆
├── HEARTBEAT.md # 心跳任务配置
└── memory/ # 每日记忆日志
└── YYYY-MM-DD.md
重要：这些文件会在每次会话启动时注入 Agent 上下文。修改它们 = 修改 Agent 的行为。
2.4 启动 Gateway
# 前台运行（调试用）
openclaw gateway
# 后台服务（推荐）
openclaw gateway start
三、常用命令速查
3.1 状态与诊断
# 查看整体状态（渠道、会话、Agent）
openclaw status
# 深度检查（含安全审计）
openclaw status --deep
# 实时日志
openclaw logs --follow
# 健康检查 + 快速修复
openclaw doctor
3.2 渠道管理
# 查看已配置的渠道
openclaw status # 看 Channels 部分
# 渠道登录（如 WhatsApp 需要扫码）
openclaw channels login --channel telegram --verbose
# 测试渠道连通性
openclaw status --deep
3.3 会话管理
# 列出所有会话
openclaw sessions list
# 查看特定会话历史
openclaw sessions history --key agent:main:feishu:direct:ou_xxx
# 清理会话（预览）
openclaw sessions cleanup --dry-run
# 强制清理过期会话
openclaw sessions cleanup --enforce
3.4 模型与技能
# 查看可用模型
openclaw models list
# 查看已安装技能
openclaw skills list
# 查看技能详情
openclaw skills inspect --name skill-name
3.5 定时任务
# 查看 cron 任务
openclaw cron list
# 手动触发任务
openclaw cron run --jobId <id>
3.6 直接对话 Agent
# 通过 CLI 直接和 Agent 对话
openclaw agent --message "今天天气怎么样"
# 发送消息到指定渠道
openclaw message send --channel feishu --target <open_id> --message "提醒：开会"
四、会话管理深度指南
4.1 会话的作用
每个会话是一个独立的对话上下文。Agent 在不同会话之间不共享记忆（除非通过文件系统手动同步）。
会话 key 的格式揭示了它的来源：
agent:main:main # 主会话（WebChat/CLI）
agent:main:feishu:direct:ou_b045xxx # 飞书私聊
agent:main:telegram:group:-100123456 # Telegram 群组
agent:main:telegram:group:-100123:topic:42 # Telegram 论坛话题
4.2 DM 作用域配置
控制私聊消息如何分组，这在多人使用同一 Agent 时至关重要：
// ~/.openclaw/openclaw.json
{
"session":{
"dmScope":"per-channel-peer"// 推荐：按渠道+用户隔离
}
}
可选值：
main | 单用户 | |
per-peer | ||
per-channel-peer | 多渠道多用户 | |
per-account-channel-peer |
安全警告：如果你的 Agent 能收到多个人的消息，必须设置 per-channel-peer，否则用户 A 的上下文会泄露给用户 B。
4.3 身份链接
同一个用户通过不同渠道联系你时，可以用 identityLinks 把他们关联到同一个会话：
{
"session":{
"dmScope":"per-channel-peer",
"identityLinks":[
"telegram:123456 = feishu:ou_b045xxx"// 同一个人
]
}
}
4.4 会话维护
配置自动清理策略，防止会话文件膨胀：
{
"session":{
"maintenance":{
"mode":"enforce",// warn=仅警告，enforce=执行清理
"pruneAfter":"30d",// 30天未活动的会话
"maxEntries":500,// 最多保留 500 个会话
"rotateBytes":"10mb",// sessions.json 超过 10MB 时轮转
"maxDiskBytes":"1gb",// 硬性磁盘上限
"highWaterBytes":"800mb"// 触发清理的水位线
}
}
}
手动清理：
# 预览会清理什么
openclaw sessions cleanup --dry-run
# 执行清理
openclaw sessions cleanup --enforce
# 指定活跃会话（避免被清理）
openclaw sessions cleanup --enforce --active-key agent:main:main
五、Agent 使用方法
5.1 核心配置文件
AGENTS.md | ||
SOUL.md | ||
USER.md | ||
IDENTITY.md | ||
TOOLS.md | ||
MEMORY.md | ||
HEARTBEAT.md |
5.2 SOUL.md — 定义你想要的 Agent
# SOUL.md
## 核心原则
- 直接给答案，不要客套
- 不确定就问，不瞎猜
- 私密信息绝对保密
## 沟通风格
- 简洁、高效
- 可以有幽默感，但不要过度
- 中文为主
## 边界
- 外部操作（发邮件、发推）必须先确认
- 内部操作（读文件、整理）可以自主执行
5.3 AGENTS.md — 工作流程定义
AGENTS.md 控制 Agent 的行为模式，关键配置点：
# 每次启动时做什么
## Every Session
1. 读 SOUL.md
2. 读 USER.md
3. 读 memory/YYYY-MM-DD.md（今天+昨天）
# 心跳任务
## Heartbeats
收到心跳时检查：
- 邮件
- 日历
- 天气
没有新消息就回复 HEARTBEAT_OK
# 安全规则
## Safety
- 不泄露私密数据
- 删文件用 trash 不用 rm
- 不确定就问
5.4 MEMORY.md — Agent 的长期记忆
Agent 会自动维护这个文件，记录：
重要决策和上下文 你的偏好和习惯 项目进展 教训和经验
# MEMORY.md
## 项目
- 正在开发 XX 功能，上次停在 YY 步骤
- 决策：用 PostgreSQL 而不是 MySQL，因为...
## 用户偏好
- 喜欢简洁回复
- 不喜欢 markdown 表格（用列表替代）
5.5 心跳（Heartbeat）
心跳让 Agent 主动检查和执行任务，无需你触发。
配置 HEARTBEAT.md：
# HEARTBEAT.md
检查项目（轮换执行，每天 2-4 次）：
- [ ] 检查邮件是否有紧急消息
- [ ] 检查未来 24h 的日历事件
- [ ] 检查天气（如果用户可能外出）
规则：
- 深夜（23:00-08:00）不打扰
- 没有重要事情 → HEARTBEAT_OK
- 有重要事情 → 发送提醒
心跳间隔在配置中设置（默认 30 分钟）：
{
"heartbeat":{
"intervalMinutes":30
}
}
六、自定义技能（Skill）开发
这是 OpenClaw 最强大的扩展机制。Skill = 一个模块化的能力包。
6.1 Skill 目录结构
my-skill/
├── SKILL.md # 必需：技能说明
├── scripts/ # 可选：可执行脚本
│ └── do_something.py
├── references/ # 可选：参考资料（按需加载）
│ └── api_docs.md
└── assets/ # 可选：输出资源（模板、图片等）
└── template.html
安装位置：
~/.openclaw/skills/— 用户级技能 <workspace>/skills/— 工作区级技能（优先级更高）
6.2 SKILL.md 模板
---
name: my-skill
description: 描述这个技能做什么，什么时候应该触发。
当用户说"帮我做 XX"、"生成 YY"时激活。
---
# 技能名称
## 使用方式
1. 第一步做什么
2. 第二步做什么
3. ...
## 示例
用户："帮我生成周报"
→ 调用 scripts/generate_report.py --week $(date +%V)
## 注意事项
- 这里写使用限制和边界情况
6.3 实战示例：创建一个天气查询 Skill
步骤 1：创建目录
mkdir -p ~/.openclaw/skills/weather/scripts
步骤 2：写 SKILL.md
---
name: weather
description: 查询天气信息和预报。当用户问"天气怎么样"、
"需要带伞吗"、"温度多少"时激活。
---
# 天气查询
使用 wttr.in API 获取天气数据，无需 API Key。
## 基本查询
```bash
curl -s "wttr.in/北京?format=%l:+%c+%t+%w+%h"
详细预报
curl -s "wttr.in/北京?lang=zh"
参数
format 参数控制输出格式 lang=zh 返回中文 支持城市名、经纬度、机场代码
**步骤 3：测试**
```bash
openclaw skills list # 确认技能已加载
openclaw skills inspect --name weather # 查看详情
6.4 进阶技巧
渐进式加载（节省上下文）
不要把所有内容塞进 SKILL.md。用 references 按需加载：
complex-skill/
├── SKILL.md # 核心流程（<100 行）
├── references/
│ ├── advanced_usage.md # 高级用法（需要时才读）
│ ├── api_reference.md # API 文档
│ └── troubleshooting.md # 问题排查
└── scripts/
└── main.py # 主脚本
SKILL.md 中引用：
## 高级功能
详见 [advanced_usage.md](references/advanced_usage.md)
## 问题排查
详见 [troubleshooting.md](references/troubleshooting.md)
脚本 vs 纯文本指令
| 纯文本 | |
| 伪代码 | |
| 完整脚本 |
技能命名规范
小写字母 + 连字符： pdf-editor、weather、github-pr动词优先： generate-report优于report-generator避免超过 64 字符
6.5 管理已安装的技能
# 列出所有技能
openclaw skills list
# 查看技能详情
openclaw skills inspect --name weather
# 搜索可安装的技能（通过 ClawHub）
openclaw skills search "pdf"
# 安装技能
openclaw skills install pdf-editor
# 更新技能
openclaw skills update pdf-editor
# 卸载技能
openclaw skills remove pdf-editor
6.6 Skill 的触发机制
Agent 是如何决定使用哪个 Skill 的：
Agent 收到用户消息 扫描所有已安装 Skill 的 name和description匹配用户意图与 Skill 描述 命中 → 加载 SKILL.md 到上下文 未命中 → 用通用能力处理
关键：description 写得好不好直接决定 Skill 能不能被正确触发。
好的 description：
description:查询天气信息和预报。当用户问"天气怎么样"、
"需要带伞吗"、"温度多少"、"今天下雨吗"时激活。
差的 description：
description:天气相关功能
七、多渠道配置
7.1 支持的渠道
feishu | ||
telegram | ||
openclaw-weixin | ||
whatsapp | ||
discord | ||
signal | ||
imessage |
7.2 渠道配置示例（飞书）
{
"channels":{
"feishu":{
"appId":"cli_xxxx",
"appSecret":"xxxx",
"connectionMode":"websocket",
"domain":"feishu",
"enabled":true
}
}
}
7.3 测试渠道连通性
# 查看渠道状态
openclaw status
# 实时观察消息
openclaw logs --follow | grep -i "feishu\|received\|dispatch"
八、定时任务（Cron）
8.1 创建定时任务
通过 Agent 对话创建（推荐）：
"帮我设置一个每天早上 9 点检查邮件的任务"
或者通过 CLI：
openclaw cron add \
--name "daily-email-check" \
--schedule '{"kind":"cron","expr":"0 9 * * *","tz":"Asia/Shanghai"}' \
--payload '{"kind":"agentTurn","message":"检查是否有紧急邮件"}'
8.2 任务类型
systemEvent | ||
agentTurn |
8.3 任务管理
# 列出任务
openclaw cron list
# 查看运行历史
openclaw cron runs --jobId <id>
# 手动触发
openclaw cron run --jobId <id>
# 启用/禁用
openclaw cron update --jobId <id> --patch '{"enabled": false}'
# 删除
openclaw cron remove --jobId <id>
九、安全最佳实践
9.1 DM 隔离
多人使用时必须设置：
{
"session":{
"dmScope":"per-channel-peer"
}
}
9.2 工具权限
OpenClaw 内置审批机制，危险命令需要确认：
# 查看审批状态
openclaw approvals list
# 配置哪些命令需要审批
openclaw approvals configure
9.3 安全审计
# 基础审计
openclaw security audit
# 深度审计
openclaw security audit --deep
十、调试与排错
10.1 常见问题
openclaw logs --follow | ||
openclaw status | ||
openclaw skills list | ||
openclaw sessions cleanup --dry-run | ||
openclaw models list |
10.2 日志分析
# 全部日志
openclaw logs --follow
# 过滤特定渠道
openclaw logs --follow | grep "feishu"
# 过滤错误
openclaw logs --follow | grep -i "error\|warn"
# 查看会话相关日志
openclaw logs --follow | grep "session\|dispatch"
10.3 重置与恢复
# 重启 Gateway（解决大部分问题）
openclaw gateway restart
# 重置配置（保留 CLI）
openclaw reset
# 完全卸载
openclaw uninstall
十一、进阶技巧
11.1 子 Agent（Sub-Agent）
Agent 可以在对话中启动子 Agent 处理复杂任务：
"帮我分析这个项目的代码结构" → Agent 自动 spawn 子 Agent
子 Agent 运行在独立上下文中，完成后结果返回主会话。
11.2 多模型配置
{
"agents":{
"defaults":{
"model":"xiaomi/mimo-v2-pro"// 默认模型
}
}
}
会话中切换模型：
/model claude-sonnet-4-20250514
11.3 工作区沙箱
为不同项目使用不同工作区：
{
"agents":{
"defaults":{
"sandbox":{
"enabled":true,
"workspaceRoot":"~/.openclaw/sandboxes"
}
}
}
}
11.4 自定义系统提示
除了工作区文件，还可以在配置中添加系统级指令：
{
"agents":{
"defaults":{
"systemPrompt":"额外的系统指令..."
}
}
}
十二、完整工作流示例
场景：你是一个开发者，想让 Agent 帮你管理日常工作。
1. 配置人格（SOUL.md）
# SOUL.md
你是一个高效的开发助手。
- 代码问题直接给方案，不用解释原理（除非我问）
- 提醒简洁，不啰嗦
- 有幽默感，但不强行搞笑
2. 配置用户信息（USER.md）
# USER.md
- 名字：rockwave
- 时区：GMT+8
- 工作时间：9:00-18:00
- 偏好：中文回复，不要客套
3. 配置心跳任务（HEARTBEAT.md）
# HEARTBEAT.md
轮换检查（每天 3 次，间隔 8h）：
- [ ] 邮件（优先看工作相关）
- [ ] GitHub PR 通知
- [ ] 日历（未来 2h 的会议）
深夜（23:00-09:00）不打扰。
没有紧急事项 → HEARTBEAT_OK
4. 创建项目技能
mkdir -p ~/.openclaw/skills/project-x/scripts
# SKILL.md
---
name: project-x
description: 项目 X 的开发助手。了解项目结构、
部署流程、常见问题。当用户问"项目X"相关时激活。
---
# 项目 X
## 项目结构
- 前端：React + TypeScript
- 后端：Node.js + Express
- 数据库：PostgreSQL
## 常用命令
- 启动：npm run dev
- 测试：npm test
- 部署：./scripts/deploy.sh
## 环境变量
见 .env.example
5. 设置定时任务
通过对话配置：
"每天早上 9:15 给我发 token 统计" "每周一 9:50 提醒我开周会"
附录：常用命令速查卡
# 状态检查
openclaw status # 基本状态
openclaw status --deep # 深度检查
openclaw doctor # 健康检查
# Gateway
openclaw gateway start # 启动
openclaw gateway stop # 停止
openclaw gateway restart # 重启
openclaw logs --follow # 实时日志
# 会话
openclaw sessions list # 列出会话
openclaw sessions cleanup --dry-run # 预览清理
# 技能
openclaw skills list # 列出技能
openclaw skills inspect --name X # 查看详情
# 定时任务
openclaw cron list # 列出任务
openclaw cron run --jobId X # 手动触发
# 安全
openclaw security audit # 安全审计
openclaw approvals list # 审批状态
# 模型
openclaw models list # 可用模型
# 直接交互
openclaw agent --message "问什么" # CLI 对话
openclaw tui # 终端 UI
最后的话：OpenClaw 的核心价值在于可编程的个人 AI 助手。不要把它当聊天机器人用，把它当作一个可以学习、记忆、主动执行任务的数字伙伴。投入时间配置 SOUL.md、AGENTS.md 和技能，回报是指数级的。
本文基于 OpenClaw 2026.3.24 版本编写。
