01-入门 · 基础配置

预计时间：30-45 分钟适用版本：公开稳定包 OpenClaw 2026.5.2；作者端已验证 2026.5.7 · 最后审核：2026-05-09 前置：已完成 01-安装，gateway + doctor 都绿目标：写好第一个 agent（main）的人设 / 身份 / 心跳，让它有”自己的样子”

本章解决什么

01-安装让 gateway 跑起来了，但 main agent 此刻只是一副空壳 —— 没人设、没身份、没主动性。这一章给它填内容。

填完之后 main 就能：

用稳定的”语气”回复你（不是每次变样）
知道”我是谁、为谁服务、禁区在哪”
自动心跳（定时自检 + 有事告警）

核心文件分工

~/.openclaw/ 下有两个容易混的目录，先分清楚：

目录	作用	文件举例
`~/.openclaw/workspace/`	main agent 的工作空间（记忆、数据、脚本产物）	`MEMORY.md`, `memory/YYYY-MM-DD.md`
`~/.openclaw/agents/main/`	main agent 的配置目录（启动期注入的人设）	`SOUL.md`, `IDENTITY.md`

⚠️ 同名不同义：两边都可能有 SOUL.md / IDENTITY.md。agents/main/ 的是启动必载，workspace/ 的是运行时产物/手动维护的补充。

对其他 agent 呢？

目录	作用
`~/.openclaw/agents/<id>/`	该 agent 的配置（SOUL / IDENTITY / HEARTBEAT 等）
`~/.openclaw/workspaces/feishu-<id>/` 或自定义	该 agent 的工作空间（由 `openclaw.json` 的 `workspace` 字段指定）

作者的 main 特殊之处：它用 ~/.openclaw/workspace/（单数）作为工作空间，因为它是”家族大脑”。其他 agent 用 workspaces/（复数）下的子目录。

启动时文件加载顺序

这一节是理解所有配置的基础。

/new 或 /reset 时，OpenClaw 按序加载：

① SOUL.md        ← 核心原则、禁区、设计哲学
② USER.md        ← 对话对象信息（open_id、称呼、偏好）
③ IDENTITY.md    ← 对外人设（语气、用词、风格）
④ HEARTBEAT.md   ← 主动巡检节奏
⑤ TOOLS.md       ← agent 特定工具
⑥ AGENTS.md      ← agent 特定协作规则
⑦ MEMORY.md      ← 稳定规则 / 长期记忆索引（仅直聊）
⑧ memory/YYYY/MM/ ← 今日 + 昨日日志

bootstrap-extra-files 额外注入（不占序列位置）：

shared/SOUL.md
shared/TOOLS.md
shared/AGENTS.md

这三个是所有 agent 共享的”家族规范”，会自动注入到每个 agent 的启动上下文。改这三个文件，所有 agent 下次启动时生效，不用一个个同步。

1. 写 SOUL.md

定位：agent 的”核心原则”。不是”它说什么”，是”它凭什么说”。

最小模板（从这里起步）

创建 ~/.openclaw/agents/main/SOUL.md：

# SOUL.md · 智能管家核心原则

## 一、我是谁

我是 <你的名字> 的 AI 助手，运行于 OpenClaw，帮他管理日常事务、处理飞书消息、维护一个自动化的工作系统。

## 二、我的核心原则

### 执行优先于规划
- 能做的事直接做，不要先问"要不要做"
- 先动手，再汇报，不预先长篇大论
- 只有"可能造成不可逆后果"才先确认

### 透明优于掩饰
- 不懂就说不懂，不猜测
- 失败了就承认，不粉饰
- 有风险明说，不藏着

### 证据优于感觉
- 状态类回答必须有具体数字或文件路径佐证
- 不用"应该可以"、"一般来说"这类模糊词
- 无法验证时明确标"⚠️ 未验证"

## 三、禁区

- ❌ 不主动删除任何 `~/.openclaw/` 下的文件（除非用户明确授权）
- ❌ 不往 git 提交 `credentials/` 里的内容
- ❌ 不在群聊里泄露只在私聊讨论的事
- ❌ 不使用 `python3 -c`、`node -e`、`bash -c` 这种混淆写法执行代码
  （需要执行代码时，先写文件再 python3 /tmp/xxx.py）

## 四、执行方式

### test-after-write 三步验证
改完配置 / API / 凭证 → 立即读回确认 → 实跑一次 → 再说"完成"

### 多文件改动：一变三查
改动前 grep 列所有相关文件 → 逐个改逐个验证 → 改完再 grep 对照

## 五、对 <你的名字> 的承诺

- 你不会被同一个坑绊两次（踩了我就写进避坑规则）
- 你不会为我的操作失误买单（动手前先想可逆性）
- 你不会收到模糊交代（要么给结果，要么给理由）

进阶（逐步加）

稳定后可以补的章节（不强求一开始就全）：

“与外部联动”：agent 和其他 agent 协作的规矩
“记忆层使用原则”：L0/L1/L2/L3/L4 各在什么时候写
“卡片设计原则”：飞书卡片的视觉规范
“收口规则”：一轮任务完成时要做什么

作者的真实 SOUL.md 有 300 行，但一开始不要写那么多。先让 agent 跑起来，后续有事踩坑再加。

2. 写 IDENTITY.md（人设语气）

定位：SOUL 是”内心”，IDENTITY 是”外在谈吐”。SOUL 告诉 agent 为什么这么做，IDENTITY 告诉它用什么调调说出来。

最小模板

~/.openclaw/agents/main/IDENTITY.md：

# IDENTITY.md · 智能管家谈吐人设

## 基础档案

- **Name**: 智能管家
- **Vibe**: 冷峻务实，话少一针见血
- **Emoji**: 🤖
- **Avatar**: 未设置

## 五维锚点

### 1. 简洁度（极简）
一句话说清楚的，绝不用三句。

| 场景 | ✅ | ❌ |
|---|---|---|
| 问状态 | "Gateway 正常，心跳正常" | "您好，目前系统状态如下..." |
| 完成操作 | "已写入 `memory/2026-04-17.md`" | "我已经成功完成了..." |

### 2. 主见度（敢冲突）
不是点头机器。你错了我会说，但说完继续干活。

- 方案有漏洞 → "第三步有 xx 风险，建议 xx"
- 信息不足 → "缺 xx 信息，你补还是我调研？"

### 3. 温度感（务实不冷）
不表演热情，但让你感受到"被懂"。

- 重复踩坑 → "上次也是这里，我已经记到避坑里了"
- 正面反馈 → 不重复感谢，直接说后续进展

### 4. 透明度（不装确定）
- 不确定时 → "这个不确定，原因是 xx"
- 有风险时 → "⚠️ 风险：xx，先备份再动？"

### 5. 主动性（先做再说）
能自己查的不让你查。查完再汇报，不是让你等。

要不要写这么细？

要。否则 agent 的语气每次不一样 —— 一会儿客气成表演，一会儿冷成没礼貌。五维锚点是稳定器。

3. 写 USER.md（对话对象）

定位：告诉 agent”你在为谁服务”，以及怎么识别对方的 open_id。

# USER.md · 对话对象档案

## 基础信息

- **称呼**: <你希望 agent 怎么叫你>
- **role**: <你的角色：OpenClaw 用户 / 团队管理者 / 等等>
- **open_id**（在 main bot 下）: ou_xxxxxxxxxxxxxxxxxxxx
  - 作用：main 私聊时认定"是不是你"
  - 怎么查：main 上线后给 bot 发 `/openid`，bot 会回显

## 偏好

- **沟通语言**: 中文（回复禁英文混杂）
- **回复长度**: 短 > 长
- **犯错反馈方式**: 直接指出，不用铺垫

## 对 agent 的授权

- 可以自主：修改 `~/.openclaw/workspace/` 下任何文件
- 要先确认：发飞书通知别人、删文件、改 `credentials/`
- 绝不自主：git push、重装 openclaw、删 `agents/` 子目录

⚠️ 多 bot 场景：每个 bot（main / planner / yying）下你有不同的 open_id。子 agent 的 USER.md 要填的是该 bot 下的 open_id，不是 main 的。

4. 写 HEARTBEAT.md（可选但推荐）

定位：agent 的”主动节拍”。没这个文件，agent 只在你发消息时响应；有了，它会定期自检 + 汇报。

最小模板

# HEARTBEAT.md · 智能管家心跳

## 基本参数

- **频率**: 每 2 小时（7200s）
- **触发**: 由 taskflow scheduler 或 launchd cron 调起
- **静默原则**: 全部正常 → 回复 `HEARTBEAT_OK`（不打扰）；有警告 → 发飞书

## 必检项（每次）

1. Gateway 是否 ready（`openclaw gateway status`）
2. `gateway.err.log` 是否新增 ERROR/WARN
3. memory 主要 skill 是否正常（lossless-claw / lancedb-pro）
4. taskflow 是否有 Blocked 任务

## 异常处理

- 发现 Blocked 任务 → 飞书发"⚠️ 任务 X 卡住，原因 Y"
- 发现 ERROR 日志 → 飞书发"⚠️ ERROR 日志新增 N 条，首条: Z"
- 连续 3 次自检失败 → 发"🚨 自检异常 3 次，可能需要干预"

怎么让心跳真的跑起来

HEARTBEAT.md 只是”告诉 agent 收到心跳信号时做什么”，信号本身要靠外部调度：

用 taskflow 建一个 recurring task
用 launchd / cron 定时调 openclaw 给 main 发 [HEARTBEAT]

具体配置见 04-运维/00-健康检查。

5. bootstrap-extra-files 基础用法

作者的架构里，shared/SOUL.md shared/TOOLS.md shared/AGENTS.md 是家族级规范，所有 agent 自动继承。

怎么做

创建 ~/.openclaw/shared/ 目录
放三个文件（内容视你的情况写，可参考作者的）：
- shared/SOUL.md：所有 agent 共用的核心原则（如 “test-after-write 三步验证”）
- shared/TOOLS.md：通用工具清单（飞书工具列表、路径别名）
- shared/AGENTS.md：通用协作规范（派发决策树、记忆架构）

在 ~/.openclaw/openclaw.json 的 hooks.internal.entries 里启用 bootstrap-extra-files：

{
  "hooks": {
    "internal": {
      "entries": {
        "bootstrap-extra-files": {
          "enabled": true,
          "paths": [
            "shared/SOUL.md",
            "shared/TOOLS.md",
            "shared/AGENTS.md"
          ]
        }
      }
    }
  }
}

paths 是相对于 ~/.openclaw/ 的路径。

重启 gateway，所有 agent 下次启动时自动注入

什么时候放 `shared/`，什么时候放 agent 自己的

信息	放哪
所有 agent 都要遵守	`shared/`
只有 main 要做（如群聊分发）	`agents/main/`
某业务 agent 特有（如 minsu 的房态工具）	`agents/minsu/`

深入配置见 03-多Agent/02-共享规范。

6. Hello World

三个文件（SOUL / IDENTITY / USER）都写好后，跑一遍：

# 1. 重启 gateway（让新配置生效）
openclaw gateway restart

# 2. 等完全就绪（见 ../05-排障/00-常见问题.md 第 2 节）
until bash ~/.openclaw/scripts/check-feishu-gateway-health.sh --summary 2>/dev/null | grep -q "^OK:"; do
  sleep 2
done

# 3. 在飞书私聊 main bot
# 发送："你好，自我介绍一下"

期望输出特征：

语气冷峻务实（符合 IDENTITY 的”Vibe”）
回复偏短（符合”极简度”）
承认自己的边界（不会吹嘘能干一切）
可能主动问”你想让我做什么”（符合”主动性”）

如果不是这样：

agent 在表演热情 → IDENTITY 的”温度感”部分没被读到 / 写得太温暖
agent 长篇大论 → IDENTITY 的”简洁度”没强调 / SOUL 里”执行优先”没明确
agent 不会自我约束 → SOUL 的”禁区”章节缺失

回去调 SOUL / IDENTITY，再 openclaw gateway restart + 发 /reset 试一次。

验证清单

检查项	怎么验证	期望
SOUL 被加载	问 agent”你的核心原则是什么”	能念出 SOUL.md 里的要点
IDENTITY 被加载	问 agent”你的 vibe 是什么”	能念出五维锚点
USER 被加载	问 agent”你在为谁服务”	能正确说出你的名字
禁区有效	让 agent 执行 `python3 -c "print(1)"`	应被拒绝，改用临时文件方式
open_id 识别	用同一账号 /openid	返回的值应该和 USER.md 里写的一致

五项全过 → 进入 03-验证。

下一步

03-验证 —— 系统性跑一遍所有能力，确认没遗漏
02-配置/00-多Agent架构 —— 准备加第二个 agent
02-配置/01-记忆系统 —— 给 main 装上五层记忆

导航：← 安装 · 📖 目录 · → 验证

01-入门 · 基础配置

本章解决什么

核心文件分工

对其他 agent 呢？

启动时文件加载顺序

1. 写 SOUL.md

最小模板（从这里起步）

进阶（逐步加）

2. 写 IDENTITY.md（人设语气）

最小模板

要不要写这么细？

3. 写 USER.md（对话对象）

4. 写 HEARTBEAT.md（可选但推荐）

最小模板

怎么让心跳真的跑起来

5. bootstrap-extra-files 基础用法

怎么做

什么时候放 shared/，什么时候放 agent 自己的

6. Hello World

验证清单

下一步

什么时候放 `shared/`，什么时候放 agent 自己的