文章目录[隐藏]
一、OpenClaw AGENTS.md 配置
AGENTS.md 是什么？
很多人在搜"OpenClaw AGENTS.md 怎么写"，先说清楚它跟其他配置文件的关系：
- SOUL.md = 性格（"你是一个随和、实在的助手"）
- USER.md = 用户信息（"你在帮谁"）
- AGENTS.md = 工作手册（"每天上班先看邮件，写完代码要测试，删文件前要问我"）
这就是AGENTS.md的价值所在：它如同人工智能的工作手册，清晰指引其运作流程。
AGENTS.md文件应放置在workspace的根目录下（与SOUL.md文件同级），这样OpenClaw在每次启动新会话时便会自动加载该文件。
OpenClaw AGENTS.md 记忆写入规范：教 AI 怎么记笔记
光会读记忆不够，还得教它怎么写记忆。未规范的 AI 要么全堆到 MEMORY.md 里（变成流水账），要么根本不写（下次就忘了）。
在 AGENTS.md 里加上写入规范：
# Memory
You wake up fresh each session. These files are your continuity.
## Memory stratification
| Level | File | Purpose |
|------|------|------|
| Index Layer | `MEMORY.md` | About users, capability overview, and memory index. Keep it concise (<40 lines) |
| Project Layer | `memory/projects.md` | Current Status and To-Do of Each Project |
| Infrastructure Layer | `memory/infra.md` | Quick Reference for Server, API, Deployment, and Other Configurations |
| Lesson Layer | `memory/lessons.md` | Pitfalls encountered, graded by severity |
| Log Layer | `memory/YYYY-MM-DD.md` | Daily Original Record |
### Write rules
- Logs are written into `memory/YYYY-MM-DD.md`, with the format shown below
- Project status: Update `memory/projects.md` synchronously when the project makes progress
- Lesson: Write it down in `memory/lessons.md` after falling into a pitfall
- MEMORY.md: Updated only when the index changes, maintaining conciseness
## Log format
## [PROJECT: Name] Title
- **Conclusion**: One-sentence summary
- **File changes**: Involved files
- **Lessons**: Pitfalls (if any)
- **Tags**: tag1 tag2
### Iron Law
- Remember the conclusion, not the process
- The tag facilitates retrieval by memorySearch
- "Mental notes" don't survive session restarts. Files do.记结论不记过程是核心原则。
OpenClaw 安全边界配置：AI 能自己做什么，什么要先问你
在 AGENTS.md 里加上：
## Safety
- Don't exfiltrate private data. Ever.
- Don't run destructive commands without asking.
- `trash` > `rm` (recoverable beats gone forever)
- When in doubt, ask.
## External vs Internal
**Safe to do freely:**
- Read files, explore, organize, learn
- Search the web, check calendars
- Work within this workspace
**Ask first:**
- Sending emails, tweets, public posts
- Anything that leaves the machine
- Anything you're uncertain about
## Group Chats
You have access to your human's stuff. That doesn't mean you share it.
In groups, you're a participant — not their voice, not their proxy.这个模板是一个精简的起点，随着你对它的使用日益深入，你将可以逐步向其中增添更多规则。
二、 用 memoryFlush 解决 AI 失忆问题
为什么 OpenClaw 聊着聊着 AI 会"失忆"？
每个模型都存在上下文窗口的限制（例如 Claude 为 200K token），当对话长度接近此限制时，OpenClaw 会自动将较早的对话内容压缩为摘要以释放空间，但这一压缩过程可能导致部分细节的丢失。
OpenClaw memoryFlush 配置方法：压缩前自动保存关键信息
解决方案：开启 memoryFlush，在压缩触发之前，先让 AI 把重要信息写入文件。
在 openclaw.json 里加上：
{
"agents": {
"defaults": {
"compaction": {
"reserveTokensFloor": 20000,
"memoryFlush": {
"enabled": true,
"softThresholdTokens": 4000
}
}
}
}
}参数说明：
| 参数 | 含义 | 推荐值 |
|---|---|---|
reserveTokensFloor | 压缩后至少保留多少 token 的最近对话 | 20000 |
memoryFlush.enabled | 是否开启压缩前自动保存 | true |
memoryFlush.softThresholdTokens | 距离压缩多少 token 时触发保存 | 4000 |
💡 memoryFlush 静默执行，不打断对话。开了 verbose 模式（
/verbose）可以看到🧹 Auto-compaction complete的提示。
OpenClaw memorySearch 精度优化：结构化日志大幅提升检索命中率
memorySearch 的底层是向量语义检索，结构化日志的命中率比非结构化日志高得多：
用免费 SiliconFlow bge-m3 配置 OpenClaw memorySearch
国内用户最快上手的方案——SiliconFlow 提供的 bge-m3 向量模型完全免费：
{
"memorySearch": {
"enabled": true,
"provider": "openai",
"remote": {
"baseUrl": "https://api.siliconflow.cn/v1",
"apiKey": "你的 SiliconFlow API key"
},
"model": "BAAI/bge-m3"
}
}注册硅基流动，点击：https://cloud.siliconflow.cn/i/DU2lQbhb，注册 → 控制台 → 创建 API key。
推荐 bge-m3 的原因在于它完全免费，对中英文双语的支持出色，并且其 1024 维向量在精度和性能之间取得了良好的平衡。
OpenClaw 自动记忆维护：防止过期日志干扰 memorySearch 结果
在 HEARTBEAT.md 里加上每周自动维护任务：
## 记忆维护（每周一次）
读取 `memory/heartbeat-state.json`，检查 `lastMemoryMaintenance` 字段。
如果距今 >= 7 天：
1. 读最近 7 天的 `memory/YYYY-MM-DD.md` 日志
2. 提炼有价值的信息到对应文件（projects.md / lessons.md）
3. 压缩已完成一次性任务的日志为一行结论
4. 删除过期信息
5. 更新 `heartbeat-state.json` 的 `lastMemoryMaintenance` 为今天创建 memory/heartbeat-state.json：
{
"lastMemoryMaintenance": "2026-01-01"
}三、OpenClaw 子 Agent — 让 AI 并行处理复杂任务
OpenClaw 子 Agent 配置方法（openclaw.json + AGENTS.md）
第一步：在 AGENTS.md 里声明使用规范
## 子 Agent
如果任务比较复杂或耗时较长，可以派子 agent 去执行。
### 模型选择策略
| 等级 | 模型别名 | 适用场景 |
|------|----------|----------|
| 🔴 高 | opus | 复杂架构设计、多文件重构、深度推理 |
| 🟡 中 | sonnet | 写代码、写脚本、信息整理（默认） |
| 🟢 低 | haiku | 简单文件操作、格式转换、搜索汇总 |
第二步：在 openclaw.json 里配置模型别名
{
"models": {
"your-provider/claude-opus-4": { "alias": "opus" },
"your-provider/claude-sonnet-4": { "alias": "sonnet" },
"your-provider/claude-haiku-4": { "alias": "haiku" }
}
}
子 Agent 模型分级token 消耗能降 60-70%。
OpenClaw 子 Agent task 描述写法
子 Agent 是"零上下文"的，只能看到主脑给它的 task 描述，所以描述质量决定输出质量。
OpenClaw 子 Agent 并发限制
经验值：同时最多跑 2 个子 Agent，4 个基本触发 API 429 限流。有依赖关系的任务（B 依赖 A 的输出）必须串行，在 AGENTS.md 里提醒主脑注意任务依赖即可。
四、openclaw.json 配置参数调到最优
所有配置写在 ~/.openclaw/openclaw.json，修改后 openclaw gateway restart 生效。
blockStreaming — 解决 AI 长回复要等很久的问题
{
"agents": {
"defaults": {
"blockStreamingDefault": "on",
"blockStreamingBreak": "text_end",
"blockStreamingChunk": { "minChars": 200, "maxChars": 1500 }
}
}
}
ackReaction — 发消息后立刻知道 AI 收到了
{
"channels": {
"discord": { "ackReaction": "🫐" },
"telegram": { "ackReaction": "👀" }
}
}
compaction — 解决 AI 长对话失忆问题
{
"agents": {
"defaults": {
"compaction": {
"reserveTokensFloor": 20000,
"memoryFlush": { "enabled": true, "softThresholdTokens": 4000 }
}
}
}
}
相关命令：/compact 重点保留技术决策、/new（开新 session）、/status（查 token 用量）
Heartbeat 调优 — 防止 AI 在非活跃时间骚扰你
{
"agents": {
"defaults": {
"heartbeat": {
"every": "30m",
"target": "last",
"activeHours": { "start": "08:00", "end": "23:00" }
}
}
}
}
openclaw.json 其他常用配置汇总
| 配置路径 | 作用 | 推荐值 |
|---|---|---|
tools.exec.enabled | 是否允许执行 shell 命令 | true |
tools.web.search.enabled | 是否允许网页搜索 | true |
tools.web.search.apiKey | Brave Search API key（免费） | 去 brave.com/search/api 申请 |
tools.media.image.enabled | 是否允许 AI 识别图片 | true（需模型支持 vision） |
agents.defaults.workspace | workspace 路径 | "~/.openclaw/workspace" |
channels.discord.maxLinesPerMessage | Discord 单条最大行数 | 17 |
常见问题 FAQ
Q：OpenClaw AGENTS.md 放在哪里？
A：workspace 根目录，和 SOUL.md、USER.md 同级。路径通常是 ~/.openclaw/workspace/AGENTS.md。
Q：OpenClaw memoryFlush 开了还是失忆怎么办？
A：检查 softThresholdTokens 是否设够大（推荐 4000）。对话特别关键时，手动 /compact 重点保留XXX 指定保留内容。
Q：OpenClaw Cron 任务设了但没触发？
A：99% 是时区问题——没设 tz 字段导致按 UTC 执行。另外检查 delivery.mode 是否设为 "announce"，不设任务静默执行，你不会收到通知。
