跳到主要内容

🚀 项目工作目录结构

详解 OpenClaw 工作目录结构，帮你理解各个目录的作用和数据存储方式

📌 核心笔记​

  • 根目录：~/.openclaw/ 是所有数据的存储位置
  • Agent 隔离：每个 Agent 有独立的 agent/ 和 sessions/ 目录
  • 工作区：workspace/ 和 workspace-coder/ 存放 Agent 的配置和记忆文件
  • 会话文件：*.jsonl 格式存储每个会话的完整对话历史

🎯 学完你能做什么​

  • 理解 OpenClaw 数据目录的组织方式
  • 定位和查看历史会话记录
  • 理解 Agent 工作区的配置文件作用
  • 知道数据备份应该备份哪些目录

😫 你现在的困境​

  • 不清楚各个目录的作用
  • 找不到历史会话记录在哪里
  • 不知道 workspace 目录下的文件是什么

🕐 什么时候用这一招​

  • 排查会话相关问题
  • 备份或迁移数据
  • 理解 Agent 的工作原理

1. 完整目录树​

~/.openclaw/
├── agents/                      # Agent 数据目录 ⭐
│   ├── coder/                   # Coder Agent
│   │   ├── SYSTEM.md            # 系统提示词（Agent 角色定义）
│   │   ├── agent/
│   │   │   └── models.json      # 模型配置（自动生成）
│   │   ├── agent.json           # Agent 配置
│   │   └── sessions/            # 会话目录
│   │       ├── *.jsonl          # 会话历史文件
│   │       └── sessions.json    # 会话索引
│   ├── main/                    # Main Agent（默认）
│   │   ├── agent/
│   │   │   └── models.json
│   │   └── sessions/
│   │       ├── *.jsonl
│   │       └── sessions.json
│   ├── pm/                      # PM Agent
│   │   ├── agent/
│   │   │   └── models.json
│   │   ├── agent.json
│   │   └── sessions/
│   └── tester/                  # Tester Agent
│       ├── agent/
│       │   └── models.json
│       ├── agent.json
│       └── sessions/
├── canvas/                      # Canvas UI
│   └── index.html
├── cron/                        # 定时任务
│   └── jobs.json
├── delivery-queue/              # 消息投递队列
│   └── failed/                  # 失败的消息
├── devices/                     # 设备配对
│   ├── paired.json              # 已配对设备
│   └── pending.json             # 待配对设备
├── feishu/                      # Feishu 插件缓存
│   └── dedup/
│       └── default.json         # 去重记录
├── identity/                    # 身份认证
│   ├── device-auth.json         # 设备认证
│   └── device.json              # 设备信息
├── logs/                        # 日志
│   └── config-audit.jsonl       # 配置审计日志
├── media/                       # 媒体文件
│   └── inbound/                 # 接收的媒体文件
│       └── *.png/*.jpg/...      # 图片、音频等
├── memory/                      # 记忆数据库 ⭐
│   ├── main.sqlite              # Main Agent 记忆库
│   └── coder.sqlite             # Coder Agent 记忆库
├── openclaw.json                # 主配置文件 ⭐
├── openclaw.json.bak*           # 备份（最多5个）
├── subagents/                   # 子 Agent
│   └── runs.json                # 运行记录
├── update-check.json            # 更新检查
├── workspace/                   # Main Agent 工作区 ⭐
│   ├── AGENTS.md               # Agent 规范
│   ├── BOOTSTRAP.md            # 启动引导
│   ├── HEARTBEAT.md            # 心跳任务
│   ├── IDENTITY.md             # 身份定义
│   ├── SOUL.md                 # 核心定义
│   ├── TOOLS.md                # 工具定义
│   ├── USER.md                 # 用户配置
│   ├── config/                 # 配置文件
│   │   └── mcporter.json
│   ├── learn-docs/             # 学习文档
│   │   └── *.md
│   ├── skills/                 # 技能定义
│   │   └── <skill-name>/
│   │       └── SKILL.md
│   └── openclaw-design-patterns.md
└── workspace-coder/             # Coder Agent 工作区 ⭐
    ├── AGENTS.md
    ├── BOOTSTRAP.md
    ├── HEARTBEAT.md
    ├── IDENTITY.md
    ├── SOUL.md
    ├── TOOLS.md
    ├── USER.md
    └── config/
        └── mcporter.json

2. 核心目录详解​

2.1 agents/ - Agent 数据目录​

每个 Agent 都有独立的目录，目录名就是 Agent ID：

agents/
├── main/      # 默认 Agent（保留字）
├── coder/     # 自定义 Agent
├── pm/        # 自定义 Agent
└── tester/    # 自定义 Agent

每个 Agent 目录下包含：

目录/文件说明
SYSTEM.mdAgent 系统提示词（定义角色和行为）
agent/Agent 运行时配置
agent/models.json模型配置（自动生成）
agent/auth-profiles.json认证凭据
agent.jsonAgent 定义配置
sessions/会话历史目录
sessions/*.jsonl单个会话的完整对话历史
sessions/sessions.json会话索引（包含会话元数据）

会话文件格式​

.jsonl 文件每行是一个 JSON 对象，记录单轮对话：

{"role": "user", "content": "你好", "timestamp": 1700000000000}
{"role": "assistant", "content": "你好！有什么可以帮你的？", "timestamp": 1700000001000}
{"role": "tool", "tool": "bash", "input": "ls", "output": "..."}

会话生命周期​

会话文件可能处于以下状态：

文件状态说明
*.jsonl活跃会话
*.jsonl.deleted.*已删除的会话（软删除）
sessions.json会话索引，包含所有会话的元数据

2.2 workspace/ - Agent 工作区​

workspace/ 目录存放 Agent 的"灵魂"文件，这些文件定义了 Agent 的行为和能力：

文件作用
AGENTS.mdAgent 规范定义
BOOTSTRAP.md启动引导流程
HEARTBEAT.md心跳任务配置
IDENTITY.md身份定义
SOUL.md核心定义（系统提示词）
TOOLS.md工具定义
USER.md用户配置
config/配置文件目录
learn-docs/学习文档目录
skills/技能定义目录
openclaw-design-patterns.md设计模式

注意：每个 Agent 可以有独立的工作区。如果 Agent 配置了 workspace 字段，则使用该路径；否则使用共享的 workspace/。

2.3 SYSTEM.md vs Workspace 文件​

在 OpenClaw 中，有两套机制来定义 Agent 的行为：SYSTEM.md 和 Workspace 文件。

SYSTEM.md​

  • 位置: agents/<agentId>/SYSTEM.md
  • 作用: Agent 级系统规范，定义代码设计原则、架构模式
  • 内容示例:
    • 适配器模式、依赖注入等设计模式
    • 代码规范（命名、函数长度）
    • 项目文件组织结构
    • Agent 特定的专业知识

Workspace 文件​

  • 位置: workspace/*.md 或 workspace-coder/*.md
  • 作用: Agent 的运行时上下文，定义如何与用户交互
  • 内容示例:
    • AGENTS.md: 操作指南、内存使用
    • SOUL.md: 人设与边界
    • USER.md: 用户信息
    • IDENTITY.md: Agent 身份

对比表​

维度SYSTEM.mdWorkspace 文件
位置Agent 目录Workspace 目录
内容代码规范、架构设计人设、交互方式、用户信息
加载时机Agent 启动时每次 Session 开始时
修改频率很少（项目级）经常（个人化）
作用对象Agent 开发者Agent 与用户交互

总结​

  • SYSTEM.md = Agent 的"工作手册"（怎么写代码）
  • Workspace 文件 = Agent 的"性格手册"（怎么与人交流）

注意：只有 coder agent 有 SYSTEM.md，因为它是专业开发者，需要代码规范。其他 agent 用默认的 workspace 文件就够了。

2.4 openclaw.json - 主配置文件​

主配置文件，包含所有运行时配置：

  • meta: 元信息（版本、上次更新时间）
  • wizard: 向导配置（上次运行信息）
  • auth: 认证配置（多账号 profiles）
  • models: 模型 Provider 配置
  • agents: Agent 列表和默认配置
  • bindings: Agent 绑定配置 ⭐
  • tools: 工具配置
  • commands: 命令配置
  • session: 会话配置
  • hooks: 钩子配置
  • channels: 消息渠道配置
  • gateway: 网关配置
  • skills: 技能配置
  • plugins: 插件配置
  • secrets: 密钥管理

bindings - Agent 绑定配置​

bindings 是将特定 Agent 绑定到特定渠道/群组的核心配置：

{
  "bindings": [
    {
      "agentId": "coder",
      "match": {
        "channel": "feishu",
        "peer": {
          "kind": "group",
          "id": "oc_6af9a63d34a5c0d534df9d45bccf5485"
        }
      }
    },
    {
      "agentId": "pm",
      "match": {
        "channel": "feishu",
        "peer": {
          "kind": "group",
          "id": "oc_f346c53567868e22aceaf3aaec29296d"
        }
      }
    }
  ]
}
字段说明
agentId要绑定的 Agent ID
match.channel消息渠道（如 feishu）
match.peer.kind对端类型（group 群组 / user 用户）
match.peer.id对端 ID（群组 ID 或用户 ID）

通过 bindings，可以实现：

  • 不同群组使用不同的 Agent
  • 将特定 Agent 分配给特定渠道或用户

session.dmScope - 会话范围​

{
  "session": {
    "dmScope": "per-channel-peer"
  }
}
值说明
per-channel-peer每个渠道的每个对端独立会话
per-sender每个发送者独立会话
main统一使用 main Agent 的会话

channels.feishu - 飞书渠道配置​

{
  "channels": {
    "feishu": {
      "enabled": true,
      "connectionMode": "websocket",
      "verificationToken": "",
      "webhookPath": "/feishu/events",
      "domain": "feishu",
      "groupPolicy": "open",
      "groups": {
        "oc_xxx": {
          "requireMention": false
        }
      },
      "appId": "cli_xxx",
      "appSecret": "xxx"
    }
  }
}
字段说明
connectionMode连接模式（websocket / webhook）
groupPolicy群组策略（open 开放 / controlled 受控）
groups群组配置
requireMention是否需要 @ 机器人

gateway.auth - 网关认证​

{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "xxx"
    }
  }
}

plugins - 插件配置​

{
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      }
    },
    "installs": {
      "feishu": {
        "source": "npm",
        "spec": "@openclaw/feishu",
        "version": "2026.3.2",
        "installedAt": "2026-03-07T13:32:38.303Z"
      }
    }
  }
}

备份文件：openclaw.json.bak, openclaw.json.bak.1 ...

2.4 memory/ - 记忆数据库​

使用 SQLite 存储向量化的记忆数据：

memory/
├── main.sqlite      # Main Agent 的记忆库
└── coder.sqlite     # Coder Agent 的记忆库

每个 Agent 可以有独立的记忆库，用于 RAG（检索增强生成）功能，让 Agent 能够记忆之前的对话和知识。

3. 功能目录说明​

3.1 canvas/ - Canvas UI​

Web UI 的静态文件目录，访问 http://localhost:18789/canvas 可查看。

3.2 cron/ - 定时任务​

定时执行的任务配置：

cron/
└── jobs.json

3.3 delivery-queue/ - 消息投递队列​

消息发送失败后的重试队列：

delivery-queue/
└── failed/         # 失败的消息（待重试）

3.4 devices/ - 设备配对​

设备配对信息，用于多设备同步：

devices/
├── paired.json      # 已配对的设备
└── pending.json     # 待配对的设备

3.5 feishu/ - Feishu 插件缓存​

飞书插件的去重和缓存：

feishu/
└── dedup/
    └── default.json    # 消息去重记录

3.6 identity/ - 身份认证​

设备身份认证信息：

identity/
├── device-auth.json    # 设备认证凭据
└── device.json         # 设备信息

3.7 logs/ - 日志目录​

运行日志和审计日志：

logs/
└── config-audit.jsonl    # 配置变更审计日志

3.8 media/ - 媒体文件​

接收的媒体文件存储：

media/
└── inbound/
    └── *.png/*.jpg/*.mp3/...    # 图片、音频、视频等

3.9 subagents/ - 子 Agent​

子 Agent 的运行记录：

subagents/
└── runs.json    # 子 Agent 调用历史

4. 数据备份指南​

4.1 必须备份​

目录/文件说明
openclaw.json主配置文件
agents/所有 Agent 的配置和会话
workspace*/Agent 工作区（包含自定义提示词）
identity/设备身份信息
memory/*.sqlite记忆数据库

4.2 可选备份​

目录/文件说明
media/inbound/媒体文件（可重新接收）
logs/日志文件

4.3 无需备份​

目录/文件说明
canvas/UI 静态文件，可重新生成
*.bak自动备份文件
update-check.json更新检查缓存
sessions/*.deleted.*已删除的会话

5. 常见问题​

Q1: 会话文件太大怎么办？​

会话文件 *.jsonl 会随着对话增长。可以手动清理旧的会话文件，或使用 openclaw session clean 命令。

Q2: 如何查找特定会话？​

查看 sessions/sessions.json 获取会话索引，每个会话有创建时间和摘要。

Q3: workspace 目录和 agents 目录的区别？​

  • workspace/: 存放 Agent 的"大脑"文件（提示词、工具定义等）
  • agents/: 存放 Agent 的运行时数据（会话、模型配置等）

Q4: 每个 Agent 有独立的记忆库吗？​

是的，memory/ 目录下可以为不同 Agent 创建独立的 .sqlite 文件，如 main.sqlite 和 coder.sqlite。

6. 检查点​

  • 理解 ~/.openclaw/ 根目录的结构
  • 能够定位历史会话文件
  • 理解 workspace 目录下的各个文件作用
  • 知道数据备份应该包含哪些目录

7. 相关文档​