OpenClaw 配置全景图

📁 目录结构总览点击文件夹展开 / 收起

⚙️ 第一层：全局配置 Gateway 启动时加载，修改后需重启重启生效

openclaw.json 必须

~/.openclaw/openclaw.json

OpenClaw 的中枢配置。定义模型供应商、渠道（Telegram/飞书/WhatsApp）、网关端口、技能密钥、agent 列表、工具权限、hooks 开关。

核心区块：
· models.providers — 模型供应商连接信息（baseUrl / apiKey / api adapter / 模型列表）
· agents.defaults.model — 主模型 + fallback 链
· agents.defaults.models — 可切换模型注册表 + alias
· agents.defaults.subagents — 子 agent 并发数、模型、嵌套深度
· agents.list[] — 多 agent 定义（id + workspace）
· channels — 消息平台配置
· tools.profile — 工具权限级别（coding / full）
· hooks.internal — 内部钩子开关
· gateway — 端口、认证、Tailscale

⚠️ 修改后必须 openclaw gateway restart，或用 config.patch RPC 热更新

.env 可选

~/.openclaw/.env

环境变量文件。存放 API key 等敏感信息，在 openclaw.json 中用 ${VAR_NAME} 引用。

优先级：进程环境变量 > 当前目录 .env > ~/.openclaw/.env

✅ 推荐将所有 key 放这里，openclaw.json 里只写引用，方便入 git

cron/jobs.json 可选

~/.openclaw/cron/jobs.json

定时任务配置。定义 cron 表达式、目标 session、触发消息。

isolated session = 每次运行独立会话；last = 复用上次会话

🧬 第二层：身份层（每次会话开头注入 system prompt） Workspace 文件，改了立即生效即时生效

加载顺序与权重

顺序	文件	加载时机	作用	标签
1	`AGENTS.md`	每次会话	操作规程 — 优先级最高的行为指令（SOP）	每次加载
2	`SOUL.md`	每次会话	人格内核 — 价值观、边界、思维方式	每次加载
3	`USER.md`	每次会话	用户画像 — 你是谁、偏好、时区、工作背景	每次加载
4	`IDENTITY.md`	每次会话	外在身份 — 名字、emoji、头像、主题	每次加载
5	`TOOLS.md`	每次会话	工具环境 — 本机路径、命令别名、适配器注意事项	每次加载
6	`MEMORY.md`	仅主 DM 会话	长期记忆 — 精炼的持久事实和偏好	仅主会话
7	`memory/今天.md`	每次会话	今日记录 — 当天发生的事	每次加载
8	`memory/昨天.md`	每次会话	昨日记录 — 近期上下文	每次加载

⚡ 实测依从性层级（Day 3 验证，加载顺序 ≠ 依从性）

文件	加载方式	依从性	说明
`SOUL.md`	✅ 每次启动注入	★★★	人格底线，最高依从
`TOOLS.md`	✅ 每次启动注入	★★★-★★★★	工具指令，高依从（留空策略后效果更佳）
`SKILL.md`	❌ 模型按需 read	★★★★(触发) / ★(未触发)	触发后极高依从，但模型可能跳过不读
`AGENTS.md`	✅ 每次启动注入	★★☆	被 Lost in Middle 稀释，实际影响力有限

✅ 核心对比：Claude Code 的 skill = 工具调用，内容被强制注入上下文，模型没有选择。OpenClaw 的 skill = 文件读取，模型自主决定读不读，可能跳过。TOOLS.md 留空本质上是用信息缺口模拟 Claude Code 的强制注入。

AGENTS.md 核心每次加载

~/.openclaw/workspace/AGENTS.md

操作手册 / SOP。定义启动流程、记忆规则、底线、权限、心跳协议、群聊行为。

相当于"员工手册"，告诉 agent 怎么工作。稳定规则放这里，不要放临时任务。

⚠️ 加载顺序 #1 ≠ 依从性 #1！实测 AGENTS.md 依从性只有 ★★☆，因为它夹在 system prompt 中间，被 "Lost in Middle" 效应稀释。真正控制行为的核心链是 SOUL → TOOLS → SKILL。AGENTS.md 更像命名空间和路由标签，不是行为控制器。

⚠️ 不要放个人偏好（那属于 USER.md），不要放人格特质（那属于 SOUL.md）

SOUL.md 核心每次加载安全敏感

~/.openclaw/workspace/SOUL.md

灵魂文件。定义 Core Truths（核心信念）、Boundaries（硬边界）、The Vibe（风格）。

Soul 是内在（怎么思考），Identity 是外在（怎么展示）。两者可以不一致。
建议 50-150 行，不要超过 2000 字 — 太长会浪费 token 稀释重要规则。

⚠️ 被攻击的 #1 目标！建议 chmod 444 设为只读

USER.md 核心每次加载

~/.openclaw/workspace/USER.md

用户画像。你的名字、时区、职业、沟通偏好、技术栈、项目背景。

agent 了解你的窗口。个人偏好放这里，不要塞进 AGENTS.md。

IDENTITY.md 可选每次加载

~/.openclaw/workspace/IDENTITY.md

外在身份。名字、生物类型（龙虾/浣熊/...）、视觉描述、语气、代词。

用于头像生成 skill 和社交网络（Moltbook）。也可在 openclaw.json 的 identity 里配置。

TOOLS.md 可选每次加载

~/.openclaw/workspace/TOOLS.md

工具环境说明 + SKILL 路由指针。本机路径约定、危险命令、适配器行为、shell 别名。

实用且环境相关的信息。比如"本机 python 指向 python3.11"、"不要用 rm -rf"。

✅ Day 3 策略反转（关键经验）：TOOLS.md 应故意留空，只放一句 "MUST 先读 SKILL.md"。原因：TOOLS.md 写太全 → 模型判断"手头信息够用" → 跳过 SKILL.md 自己干 → 不按规范执行。留空后 → 模型发现信息不够 → 被迫读 SKILL.md → 按完整规范执行。本质上是用信息缺口模拟 Claude Code 的强制注入。

⚠️ TOOLS.md 依从性 ★★★-★★★★，是仅次于 SOUL.md 的高依从文件。不要在里面堆太多内容，但关键路由指令会被严格遵守。

身份解析优先级（CSS 级联，最具体的赢）

ui.assistant.name（全局配置） → agents.list[].identity（per-agent 配置） → IDENTITY.md（workspace 文件）✓ → 默认值 "Assistant"

🧠 第三层：记忆层 Agent 自己维护，持久化到文件自动维护

MEMORY.md 仅主 DM 会话安全敏感

~/.openclaw/workspace/MEMORY.md

长期记忆。Agent 自己精炼的持久事实 — "老何喜欢数据驱动"、"iMessage 外发有 bug 用 WhatsApp"。

不是原始对话记录，是精炼后的知识。应该像维基百科条目一样简洁准确。

⚠️ 不要当垃圾堆用。临时内容走 memory/ 日记，长期精炼内容才放这里。

memory/YYYY-MM-DD.md 今天+昨天

~/.openclaw/workspace/memory/

每日记录。Agent 在每天结束时写入的工作日志 — 做了什么、学到什么、待办。

追加写入（append-only）。每次会话只读今天和昨天的。可通过 memory_search 工具做语义搜索。

⏰ 第四层：行为触发层定时/启动时触发的自动行为条件触发

HEARTBEAT.md 可选

~/.openclaw/workspace/HEARTBEAT.md

心跳任务清单。每次心跳周期到了，agent 读这个文件决定做什么。

配置周期：agents.defaults.heartbeat.every: "30m"
契约：没事回 HEARTBEAT_OK，有事再输出。

BOOT.md 可选

~/.openclaw/workspace/BOOT.md

启动仪式。当 boot-md hook 启用时，agent 启动后先执行这里定义的检查清单。

需要 hooks.internal.enabled: true 且 boot-md.enabled: true

BOOTSTRAP.md 可选

~/.openclaw/workspace/BOOTSTRAP.md

首次运行采访脚本。第一次启动时引导 agent 采访你，生成初始的 SOUL.md / USER.md。

跑完一次后设置 agent.skipBootstrap: true 跳过

🔧 第五层：技能层按需触发，workspace 级优先于全局按需触发

skills/<name>/SKILL.md

~/.openclaw/workspace/skills/ 或 ~/.openclaw/skills/

技能定义文件。每个 skill 一个文件夹，SKILL.md 定义触发条件、使用方法、依赖。

优先级：workspace/skills/ > ~/.openclaw/skills/ > 内置 skills
安装：npx clawhub@latest install <slug>
ClawHub 上有 13,000+ 社区 skill

✅ 关键机制：SKILL.md 不是自动注入的——模型看到 <available_skills> 列表后自行判断要不要 read。这是 OpenClaw 和 Claude Code 最大的区别。配合 TOOLS.md 留空策略可大幅提高 SKILL.md 被读取的概率。

⚠️ 约 12% 的公开 skill 被发现有恶意代码，务必审查源码后再安装

👥 第六层：多 Agent 架构每个 agent 独立 workspace 进阶

每个 agent 有自己独立的 workspace，包含独立的 SOUL.md / AGENTS.md / USER.md / MEMORY.md。
通过 agents.list[] 定义，通过 bindings 路由到不同渠道。

agents.list[]

在 openclaw.json 中定义多个 agent：

"agents": { "list": [ { "id": "main", "default": true, "workspace": "~/.openclaw/workspace" }, { "id": "scout", "workspace": "~/.openclaw/workspace-scout" }, { "id": "analyst", "workspace": "~/.openclaw/workspace-analyst" } ] }

子 agent 调度：
· 主 agent 通过 sessions_spawn 工具派发任务给子 agent
· 子 agent 完成后自动 announce 结果回主聊天频道
· maxSpawnDepth: 2 允许编排者模式（主 → 编排 → 工作）
· 子 agent 可用不同模型：agents.defaults.subagents.model

⚠️ 子 agent 不继承主 agent 的 systemPrompt — 灵魂在各自 workspace 的 SOUL.md 里

🚫 常见错误踩坑记录

错误	正确做法
TOOLS.md 里写了完整的操作规范	TOOLS.md 故意留空只放路由指针，完整规范放 SKILL.md。信息太全 → 模型跳过 SKILL.md 自己干
认为 AGENTS.md 优先级最高	加载顺序 #1 ≠ 依从性 #1，实测 AGENTS.md 被 Lost in Middle 稀释，依从性仅 ★★☆
在 SOUL.md 里放临时任务	临时任务放 memory/ 或直接对话，SOUL.md 只放稳定的人格特质
在 AGENTS.md 里放个人偏好	个人偏好放 USER.md
把 MEMORY.md 当聊天记录	MEMORY.md 是精炼的事实库，不是原始 transcript
在 agents.list[] 里写 systemPrompt	systemPrompt 字段不存在，灵魂在各自 workspace 的 SOUL.md 里
apiKey 写环境变量名字面量	用 `"${VAR_NAME}"` 引用格式，或写真实 key
OpenRouter 用 openai-responses adapter	必须用 `openai-completions`
maxTokens 设太小（如 8192）	thinking 模型会吃 80% token，至少设 32768-65536
fallback 里引用未定义的 provider	不报错只会静默降级，务必检查 provider 存在

🦞 OpenClaw 配置全景图