OpenClaw工作空间文件解密-夜雨聆风

OpenClaw工作空间文件解密

你有没有想过，一个AI Agent的”大脑”长什么样？

不是代码，不是模型，而是一个个简单的Markdown文件。

OpenClaw这个明星项目（GitHub 372k Star）的工作空间，就是由这些文件组成的。今天带你拆解它的底层逻辑。

Agent Workspace（工作空间）是什么

Agent Workspace是OpenClaw Agent的”家”。它不是沙箱，是Agent唯一的工作目录。默认路径：~/.openclaw/workspace。

这里的每个文件，都会在会话开始时注入到System Prompt里。

相当于每次对话前，Agent都要”复习一遍自己的记忆”。

核心文件拆解

AGENTS.md – 操作指令

这是Agent的”操作手册”。规则、优先级、行为准则全在这里。

比如你见过的那些”铁律”系统，就写在这个文件里。每次新会话启动，OpenClaw都会加载它。

关键特性：

1. 每次会话必加载

2. 适合放长期规则

3. 文件过大时会被截断（默认12000字符）

SOUL.md – 人格与边界

如果说AGENTS.md是”规矩”，SOUL.md就是”性格”。

它定义Agent的语气、边界和人设。比如”我是你的知识官，直接简洁，不爱啰嗦”。

官方文档专门有一篇[SOUL.md Personality Guide](https://docs.openclaw.ai/concepts/soul)来教你怎么写好它。

USER.md – 用户画像

“你是谁”的回答。

写在这里的信息，Agent会记住。称呼、背景、偏好、时区等。

IDENTITY.md – 身份标识

Agent的名字、风格、emoji。在Bootstrap仪式中创建和更新。

TOOLS.md – 工具约定

注意，这个文件不控制工具的可用性。它只是指导性的备注，记录你希望Agent如何使用本地工具的约定。

HEARTBEAT.md – 心跳检查清单

可选的微型检查清单。给Heartbeat机制用的。

Heartbeat是OpenClaw的一个强大功能——Agent可以定期主动检查任务状态。比如每30分钟检查一次未完成的To-Do。

配置示例：

{
agents: {
defaults: {
heartbeat: {
every: “30m”,
target: “last”,
},
},
},
}

BOOT.md – 启动清单

Gateway重启时自动执行。适合放那些”每次重启都要做的事”。

BOOTSTRAP.md – 首次运行仪式

一次性文件。只在全新工作空间时生成。完成Bootstrap仪式后应该删除它。

记忆系统文件

memory/YYYY-MM-DD.md – 每日记忆日志

每天一个文件。推荐在会话启动时读取今天和昨天的日志。

MEMORY.md – 长期记忆

经过提炼的持久记忆。存放核心事实、偏好、决策和简短摘要。

重要提醒：只在主会话（private session）中加载，不要在共享/群组环境中加载。

Skills（技能）系统

OpenClaw的Skills系统非常强大。每个Skill是一个文件夹，包含一个SKILL.md文件。

优先级从高到低：

优先级	来源	路径
1	工作空间技能	`<workspace>/skills`
2	项目Agent技能	`<workspace>/.agents/skills`
3	个人Agent技能	`~/.agents/skills`
4	管理/本地技能	`~/.openclaw/skills`
5	内置技能	随安装打包
6	额外技能目录	`skills.load.extraDirs`

同名Skill，优先级高的覆盖低的。

配置文件 openclaw.json

配置文件不在工作空间里，它放在~/.openclaw/openclaw.json。

最小配置示例：

{
agents: { defaults: { workspace: “~/.openclaw/workspace” } },
channels: { whatsapp: { allowFrom: [“+15555550123”] } },
}

核心配置项：

配置项	作用
agents.defaults.workspace	工作空间路径
agents.defaults.model	主模型和备选模型
agents.defaults.sandbox	沙箱模式(off/non-main/all)
session.dmScope	DM隔离策略
channels	各频道配置
skills.entries	技能配置和API Key

配置热重载是默认开启的。修改配置不需要重启Gateway。

会话管理（Session）

OpenClaw把对话组织成Session。每个消息根据来源路由到不同的Session。

来源	行为
私信	默认共享会话
群聊	每个群组隔离
Cron任务	每次运行新会话
Webhook	每个Webhook隔离

会话生命周期：

1. Daily Reset：默认凌晨4点自动新开Session

2. Idle Reset：可配置空闲超时（如120分钟）

3. Manual Reset：输入/new或/reset手动重置

Multi-Agent路由

OpenClaw支持多Agent部署。每个Agent有自己的工作空间和Session。

{
agents: {
list: [
{ id: “home”, default: true, workspace: “~/.openclaw/workspace-home” },
{ id: “work”, workspace: “~/.openclaw/workspace-work” },
],
},
bindings: [
{ agentId: “home”, match: { channel: “whatsapp”, accountId: “personal” } },
{ agentId: “work”, match: { channel: “whatsapp”, accountId: “biz” } },
],
}

架构核心概念

OpenClaw的架构基于一个核心设计：Gateway（网关）。

1. 单个Gateway管理所有消息通道（WhatsApp/Telegram/Slack/Discord/微信/飞书等）

2. 客户端通过WebSocket连接到Gateway（默认127.0.0.1:18789）

3. Node设备（macOS/iOS/Android）也通过WebSocket连接，声明role: node

4. 一个Gateway就是一个控制平面

支持的频道数量惊人：WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, IRC, Microsoft Teams, Matrix, Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo, WeChat, QQ, WebChat。

安全模型

OpenClaw采用单一可信操作者（Trusted Operator）模型。

1. 认证通过的Caller被视为该Gateway的信任操作者

2. 默认DM策略是pairing——未知发送者会收到配对码

3. 沙箱模式可以隔离非主会话的执行环境

4. Session ID是路由控制，不是用户权限边界

重要提醒：不要把工作空间中的API Key提交到公开仓库。

为什么这些文件如此重要

因为这就是AI Agent的”灵魂”所在。

没有这些文件，Agent只是一个空洞的模型。有了它们，Agent变成了有性格、有记忆、有规则的助手。

这比任何复杂的代码架构都更值得你花时间去打磨。

你的Agent工作空间，准备好了吗？

— 本文来自微信公众号 —