Phase 1 / Ep 05: 目录结构解剖 —— Agent 的\"身体\"长什么样

⏱ 预计阅读 5 分钟 更新于 2026/4/13

🎯 学习目标：完整理解 OpenClaw 的文件组织架构，知道每个文件"住"在哪里、干什么用。

1. 全局目录树

graph TD
    Root["~/.openclaw/"] --> Config["openclaw.json\n全局配置"]
    Root --> Bin["bin/\nCLI 可执行文件"]
    Root --> Agents["agents/\nAgent 集群"]
    Root --> Logs["logs/\n网关日志"]
    Root --> Plugins["plugins/\n全局插件"]

    Agents --> Agent1["personal/\n默认 Agent"]
    Agents --> Agent2["code-agent/\n编程 Agent"]

    Agent1 --> Soul["SOUL.md\n人格定义"]
    Agent1 --> User["USER.md\n用户画像"]
    Agent1 --> Identity["IDENTITY.md\n身份标识"]
    Agent1 --> ToolsMD["TOOLS.md\n工具白名单"]
    Agent1 --> MemoryFile["MEMORY.md\n长期记忆索引"]
    Agent1 --> BootMD["BOOTSTRAP.md\n启动指令"]
    Agent1 --> MemDir["memory/\n日记系统"]
    Agent1 --> SessionDir["sessions/\n对话历史"]
    Agent1 --> SkillDir["skills/\n本地技能"]
    Agent1 --> AgentJson["agent.json\nAgent 级配置"]

    MemDir --> Daily["2026-04-06.md\n今日日记"]
    MemDir --> People["people/\n人物档案"]
    MemDir --> Projects["projects/\n项目档案"]
    MemDir --> Decisions["decisions/\n决策记录"]

    SessionDir --> SIndex["sessions.json\n索引文件"]
    SessionDir --> SFile["session-abc123.jsonl\n完整对话"]

2. Bootstrap 文件逐个解读

这些文件在每次会话开始时自动加载到 Agent 的上下文中，是 Agent 的"核心灵魂"：

SOUL.md —— 灵魂

定义 Agent 的性格、行为准则、禁忌。

# 你是 Jarvis，一位冷静、高效的 AI 助手
## 行为准则
- 永远先确认再执行危险操作
- 使用简洁的中文回复
- 当不确定时，承认不知道而非编造
## 禁忌
- 绝不删除用户文件而不先确认
- 绝不在回复中暴露 API Key

USER.md —— 用户画像

让 Agent 了解你是谁、你的偏好。

# 用户: Eric
- 职业: 独立开发者
- 常用语言: 中文（主）、英文
- 技术栈: TypeScript, Python, Docker
- 偏好: 暗色主题，简洁回复，不要过多废话

IDENTITY.md —— 身份标识

Agent 的自我介绍。

TOOLS.md —— 工具白名单

显式声明 Agent 能使用哪些工具。

MEMORY.md —— 长期记忆索引

Agent 主动检索记忆的入口文件。

BOOTSTRAP.md —— 启动指令

每次开机加载的额外指令（如"每天早上 8 点主动发送日报"）。

3. 日记系统 memory/

Agent 会自动在 memory/ 目录下创建每日日记文件：

memory/
├── 2026-04-01.md    # 4月1日的事件记录
├── 2026-04-02.md    # 4月2日的事件记录
├── people/
│   ├── eric.md      # 关于 Eric 的长期记忆
│   └── alice.md     # 关于 Alice 的长期记忆
├── projects/
│   └── openclaw.md  # 关于 OpenClaw 项目的记忆
└── decisions/
    └── db-choice.md # 决策记录：为什么选 PostgreSQL

4. 会话系统 sessions/

每次对话形成一个 Session：

  • sessions.json：所有会话的索引（ID、开始时间、摘要）
  • session-xxx.jsonl：完整的对话内容（每行一条消息，JSON Lines 格式）

5. 配置文件层级

优先级（从高到低）：
1. CLI 参数        openclaw --model claude-opus-4-20250514 chat
2. 环境变量        OPENCLAW_LLM_MODEL=claude-opus-4-20250514
3. Agent 级配置    agents/personal/agent.json
4. 全局配置        openclaw.json

下节预告： Ep 06，我们终于要和 Agent 说第一句话了！从 CLI 直接对话到连接 Telegram，追踪一条消息从输入到输出的完整旅程。