从入门到高手

一份关注实用操作的 OpenClaw 使用手册，涵盖会话管理、技能开发、Agent 使用和常用命令。

一、核心概念速览

OpenClaw 本质上是一个 AI Agent 运行时，它把大模型、工具调用、多渠道通信整合在一起。几个关键概念：

核心架构：用户通过 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"// 推荐：按渠道+用户隔离
}
}

可选值：

安全警告：如果你的 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 核心配置文件

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 的：

1. Agent 收到用户消息
2. 扫描所有已安装 Skill 的 name 和 description
3. 匹配用户意图与 Skill 描述
4. 命中 → 加载 SKILL.md 到上下文
5. 未命中 → 用通用能力处理

关键：description 写得好不好直接决定 Skill 能不能被正确触发。

好的 description：

description:查询天气信息和预报。当用户问"天气怎么样"、
"需要带伞吗"、"温度多少"、"今天下雨吗"时激活。

差的 description：

description:天气相关功能

七、多渠道配置

7.1 支持的渠道

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 任务类型

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 常见问题

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 版本编写。