夜雨聆风想让多个AI助手协同工作？想让每个Agent都拥有独立人格？本文带你彻底搞懂OpenClaw的目录结构和核心配置文件。
导语
很多开发者在使用OpenClaw时都会遇到这些问题：
✋ Agent之间人格混乱，搞不清谁是谁 ✋ 配置文件一堆参数，不知道每个字段是啥意思 ✋ 想搭建AI团队，但不知道目录怎么组织才合理 ✋ 修改了配置却不生效，因为没写对位置
其实，这些问题都源于一个核心概念：OpenClaw只认一个"宪法"——openclaw.json文件。
今天这篇文章，我将带你彻底搞懂OpenClaw的目录结构和核心配置，让你从配置小白进阶为AI团队管理大师 🚀
一、OpenClaw核心目录：从物理隔离到逻辑分离
OpenClaw的设计理念很简单：工作内容和运行状态要分开。就像公司里，员工的岗位职责（工作内容）和员工档案（运行状态）要分开管理一样。
📂 核心目录全景图
🏢 workspace/：Agent的"办公桌"
通俗理解：每个Agent都有自己的工作空间，就像每个员工都有独立的办公桌，上面放着他的岗位职责书、工作笔记、常用工具等。
存放内容：
📋 人格文件：SOUL.md（我是谁）、USER.md（服务对象）、IDENTITY.md（性格特点） 🧠 记忆文件：MEMORY.md（长期记忆）、memory/2026-03-21.md（每日笔记） 🛠️ 技能包：skills/目录，存放模块化任务流程 ⏰ 节奏文件：HEARTBEAT.md（定时检查）、BOOTSTRAP.md（新手引导）
关键点：
不同Agent必须有独立的workspace，否则人格会混乱 workspace路径在openclaw.json中为每个Agent单独配置
🗂️ agents/：Agent的"档案柜"
通俗理解：存放每个Agent的系统级状态信息，比如认证信息、模型配置、会话历史等，相当于员工的人事档案。
典型结构：
agents/
└── main/ # Agent ID
├── agent/ # 对应 openclaw.json 中的 agentDir
│ ├── auth.json # 认证配置（工卡）
│ └── models.json # 模型配置（能力级别）
└── sessions/ # 会话历史（工作日志）
├── sessions.json # 日志索引
└── *.jsonl # 具体记录
关键点：
agentDir是配置字段，可以自定义路径 ⚠️ 切勿跨Agent共用agentDir，会导致会话混乱
🔌 extensions/：插件目录
通俗理解：存放连接飞书、Discord等第三方通讯软件的插件文件。连接后会自动生成对应文件夹。
二、openclaw.json：掌控AI团队的"宪法"
📍 核心认知
OpenClaw系统只认openclaw.json中的配置！
磁盘上创建的目录只有被配置文件正确引用，对应的Agent才真正"存在"。就像公司里，只有HR系统里登记的员工才算正式入职。
🎛️ 配置文件完整解读
1️⃣ agents：Agent注册表（最核心）
{
"agents": {
"defaults": { // 所有Agent的默认配置
"workspace": "~/.openclaw/workspace", // 默认办公桌位置
"model": {
"primary": "anthropic/claude-opus-4-5", // 主力模型
"fallbacks": ["openai/gpt-5.2"] // 备用模型（故障转移）
},
"thinkingDefault": "low", // 思考深度：low/high/off
"timeoutSeconds": 600, // 任务超时时间
"maxConcurrent": 3, // 最大并发任务数
"compaction": { // 记忆压缩配置
"reserveTokensFloor": 20000, // 压缩后至少保留多少token
"memoryFlush": {
"enabled": true,
"softThresholdTokens": 4000 // 距离阈值多少时触发压缩
}
},
"heartbeat": { // 定时心跳配置
"every": "30m", // 检查间隔：15m/30m/1h
"activeHours": {
"start": "08:00",
"end": "23:00" // 活跃时段
}
},
"subagents": {
"allowAgents": [] // 默认不允许调用其他Agent
}
},
"list": [ // ⭐ 注册的Agent列表
{
"id": "main", // 唯一标识（必填）
"name": "主助手",
"workspace": "~/.openclaw/workspace",
"agentDir": "~/.openclaw/agents/main/agent",
"model": { // 可以覆盖默认配置
"primary": "zai/glm-5",
"fallbacks": ["zai/glm-4-7", "deepseek/deepseek-chat"]
},
"subagents": {
"allowAgents": ["researcher", "writer"] // 白名单
}
}
]
}
}
通俗解释：
defaults：公司通用规定（所有员工都适用） list：员工名单（系统只认这里登记的员工） agentDir：员工档案柜位置（每个员工独立） allowAgents：允许协作的同事（白名单机制）
2️⃣ models：模型提供商配置
{
"models": {
"mode": "merge", // 与内置提供商合并
"providers": {
"zai": { // 自定义提供商名称
"apiKey": "${ZAI_API_KEY}", // ⚠️ 使用环境变量
"api": "zai-api",
"models": [{
"id": "zai/glm-5",
"name": "智谱GLM-5",
"contextWindow": 200000, // 上下文窗口大小
"maxTokens": 8192 // 最大输出token数
}]
},
"my-proxy": {
"baseUrl": "http://localhost:4000/v1",
"apiKey": "YOUR_KEY",
"api": "openai-completions" // 支持多种协议
}
}
}
}
通俗解释：
定义AI模型从哪里来（OpenAI、Anthropic、自建代理等） 每个Agent可以分配不同的模型（级别不同）
3️⃣ channels：通讯渠道配置
{
"channels": {
"feishu": {
"enabled": true,
"appId": "cli_xxxxxx",
"appSecret": "${FEISHU_SECRET}", // ⚠️ 使用环境变量
"dmPolicy": "allowlist", // 私聊策略：allowlist/pairing/open
"allowFrom": ["ou_xxxxxx"] // 允许的用户ID
},
"discord": {
"enabled": true,
"token": "${DISCORD_TOKEN}",
"allowFrom": ["server:服务器ID"],
"ackReaction": "🫐" // 收到消息后的回复表情
}
}
}
通俗解释：
配置Agent通过哪些渠道接收消息（飞书、Discord、WhatsApp等） dmPolicy：私聊安全策略 allowlist：白名单模式（只允许指定用户）pairing：配对模式（需要先配对）open：开放模式（任何人都能联系，⚠️不安全）
4️⃣ gateway：网关服务配置
{
"gateway": {
"mode": "local",
"port": 18789,
"bind": "loopback", // 只监听本地（默认）
"auth": {
"mode": "token",
"token": "your-secret-token" # 访问密钥
}
}
}
通俗解释：
OpenClaw的网关服务，用于远程控制和API调用 默认只监听本地，确保安全
5️⃣ tools：工具权限控制
{
"tools": {
"profile": "coding", // 预设工具组
"deny": ["browser", "canvas"], // 禁用工具
"allow": ["exec"], # 允许工具（优先级高于profile）
"elevated": { // 权限提升配置
"enabled": true,
"allowFrom": {
"whatsapp": ["+15555550123"] # 白名单用户可以提升权限
}
}
}
}
通俗解释：
控制Agent可以使用哪些工具（浏览器、代码执行、文件操作等） elevated：类似sudo权限，需要明确授权
三、配置实战：从零搭建AI团队
🎯 最小化配置（快速上手）
{
"agents": {
"defaults": {
"workspace": "~/.openclaw/workspace"
}
},
"channels": {
"whatsapp": {
"enabled": true,
"allowFrom": ["+你的手机号"]
}
}
}
一句话说明：配置一个工作区和一个通讯渠道，立即开始使用！
🏢 多Agent协作（推荐架构）
~/.openclaw/
├── openclaw.json # 宪法文件
├── workspace-main/ # 主调度员工作区
├── agency-agents/ # 专业Agent工作区
│ ├── researcher/ # 研究员
│ ├── writer/ # 作家
│ └── coder/ # 程序员
├── agents/ # 所有Agent的档案柜
│ ├── main/
│ ├── researcher/
│ ├── writer/
│ └── coder/
└── skills/ # 共享技能库
└── shared-skills/ # 所有Agent都能用的技能
配置示例：
{
"agents": {
"list": [
{
"id": "main",
"name": "调度员",
"workspace": "~/.openclaw/workspace-main",
"agentDir": "~/.openclaw/agents/main/agent",
"subagents": {
"allowAgents": ["researcher", "writer", "coder"]
}
},
{
"id": "researcher",
"name": "研究员",
"workspace": "~/.openclaw/agency-agents/researcher",
"agentDir": "~/.openclaw/agents/researcher/agent"
}
]
}
}
🔒 安全最佳实践
1️⃣ API密钥管理
// ❌ 错误做法
"apiKey": "sk-xxxxxxxxxxxxxxxx"
// ✅ 正确做法
"apiKey": "${ZAI_API_KEY}" // 使用环境变量
2️⃣ 权限控制
{
"channels": {
"feishu": {
"dmPolicy": "allowlist", // 使用白名单
"allowFrom": ["ou_xxxxxx"] // 只允许指定用户
}
},
"agents": {
"defaults": {
"subagents": {
"allowAgents": [] // 默认不允许跨Agent调用
}
}
}
}
3️⃣ 文件系统保护
{
"filesystem": {
"defaultPolicy": "deny", // 默认拒绝所有文件访问
"allow": [ // 逐个开放路径
"~/.openclaw/workspace/**"
]
}
}
⚡ 性能优化技巧
1️⃣ 模型分级策略
{
"agents": {
"list": [
{
"id": "main",
"model": {
"primary": "anthropic/claude-3-haiku" // 日常任务用轻量模型
}
},
{
"id": "researcher",
"model": {
"primary": "anthropic/claude-opus-4" // 复杂推理用重量模型
}
}
]
}
}
2️⃣ 心跳 vs Cron
心跳（HEARTBEAT.md）：适合需要对话上下文的任务（检查收件箱、待办提醒） Cron定时任务：适合独立执行的任务（每日简报、数据备份）
3️⃣ 记忆压缩优化
{
"agents": {
"defaults": {
"compaction": {
"memoryFlush": {
"enabled": true, // 开启记忆刷新
"softThresholdTokens": 4000 // 提前触发压缩
}
}
}
}
}
四、核心概念速查表
| 概念 | 配置文件/目录 | 本质 | 通俗类比 |
|---|---|---|---|
| Agent人格 | workspace/SOUL.md | 性格、身份、使命 | 岗位职责说明书 |
| Agent状态 | agents/ |
认证、配置、模型 | 员工档案卡 |
| 系统宪法 | openclaw.json | 注册表、路由表、权限表 | 公司HR系统 |
| 会话历史 | agents/ |
对话记录 | 工作日志本 |
| 共享技能 | ~/.openclaw/skills/ | 跨Agent复用流程 | 公共培训手册 |
| 私有技能 | workspace/skills/ | 单Agent专属流程 | 个人工作笔记 |
五、常见问题排查
❓ 配置不生效怎么办？
检查清单：
✅ openclaw.json 语法是否正确（运行 openclaw config validate）✅ Agent是否在 agents.list中注册✅ workspace 和 agentDir 路径是否正确 ✅ 修改后是否重启了服务
❓ Agent人格混乱怎么办？
原因：多个Agent共用同一个workspace
解决：为每个Agent配置独立的workspace路径
❓ 会话记录丢失怎么办？
原因：agentDir 配置错误或跨Agent共用
解决：检查 openclaw.json 中的 agentDir 配置
❓ 如何查看已注册的Agent？
命令：
openclaw agents list
总结
OpenClaw的核心在于理解两个概念：
目录分离：workspace（工作内容）和 agents（运行状态） 配置为王：openclaw.json 是系统唯一信任的"宪法"
记住这三条黄金法则：
📋 所有Agent必须在 openclaw.json 中注册 🗂️ 每个Agent必须有独立的 workspace 和 agentDir 🔒 永远不要在配置文件中明文存储密钥
掌握了这些，你就能搭建出高效、安全、可扩展的AI团队了！🎉
如果你觉得这篇文章对你有帮助，欢迎点赞、收藏、转发给更多开发者！
有任何问题，欢迎在评论区留言，我会一一解答 💬
