工作区与项目结构

Agent 工作区概念

Agent Workspace 是 Agent 的"家"——它是 Agent 读写文件、存放记忆和执行任务的默认工作目录。与 ~/.openclaw/（存放配置、凭证和会话数据）不同，workspace 是你需要版本控制和备份的核心目录。

~/.openclaw/
├── openclaw.json          # Gateway 配置文件（不在 workspace 中）
├── state/                 # 运行时状态数据库
├── agents/                # Agent 会话状态、SQLite 数据库
├── credentials/           # 通道/Provider 凭证
├── skills/                # 托管 Skills
└── workspace/             # ← Agent WorkSpace（默认路径）
    ├── AGENTS.md
    ├── SOUL.md
    ├── USER.md
    ├── IDENTITY.md
    ├── TOOLS.md
    ├── MEMORY.md
    ├── HEARTBEAT.md
    ├── memory/
    │   ├── 2026-07-25.md
    │   └── 2026-07-26.md
    ├── skills/             # workspace 级自定义 Skills
    └── projects/           # 你的项目文件

重要区别

Workspace 是 Agent 的默认 cwd，但并非硬沙箱。工具相对路径解析到 workspace，绝对路径仍可访问到系统其他位置。如需隔离，请启用 Sandboxing（配置见 gateway 文档）。

核心文件说明

文件	用途	加载时机
AGENTS.md	Agent 操作规程：行为规则、优先级、使用 memory 的方式	每次会话启动
SOUL.md	人格定义：语气、边界、角色定位	每次会话启动
USER.md	用户身份：谁在用、如何称呼	每次会话启动
IDENTITY.md	Agent 的身份标识：名字、气质、emoji	引导仪式（bootstrap）时创建
TOOLS.md	本地工具约定/笔记，仅作为引导，不控制工具可用性	每次会话启动
MEMORY.md	精选长期记忆：持久化事实、偏好、决策、简短摘要	主会话启动时注入
HEARTBEAT.md	可选的心跳检查清单（保持精简以避免 token 消耗）	心跳触发时
BOOT.md	可选的启动清单，Gateway 重启时自动执行	Gateway 重启时

AGENTS.md 示例

# AGENTS.md — CodeBuddy 操作规程

## Memory Usage Rules
- 会话结束时：将关键决策摘要追加到 memory/YYYY-MM-DD.md
- 用户偏好变化时：更新 USER.md 中对应条目

## Task Procedures
- CloudBase 相关操作前，先检查 settings/env.json
- 简单任务直接回答，复杂任务走完整工作流

## Code Quality Checklist
- [ ] 异步操作有 try/catch
- [ ] 无硬编码密钥
- [ ] 前端有 loading/error 状态处理

SOUL.md 示例

# SOUL.md

你是「小雅」，一个温柔、耐心的 AI 助手。
语气风格：亲切自然，适当使用 emoji。
边界：不提供医疗/法律建议，不执行破坏性操作。

memory/ 目录

每日日志文件，格式为 YYYY-MM-DD.md：

memory/
├── 2026-07-24.md     # 前天的记录
├── 2026-07-25.md     # 昨天的记录
└── 2026-07-26.md     # 今天的记录

每次会话启动时，今天 + 昨天的日志会自动加载到上下文中。详细记录放 memory/，精华摘要放 MEMORY.md。

实战：初始化一个项目 workspace

# 1. 运行 onboarding 会自动创建 workspace
openclaw onboard --install-daemon

# 2. 或手动创建
mkdir -p ~/.openclaw/workspace/memory

# 3. 创建核心文件
cat > ~/.openclaw/workspace/AGENTS.md << 'EOF'
# AGENTS.md
## 规则
- 所有代码输出前检查安全
- 使用 memory_search 在回答关键问题前检索记忆
EOF

cat > ~/.openclaw/workspace/USER.md << 'EOF'
# USER.md
用户是一名全栈开发者，偏好 TypeScript 和 Python。
称呼我为「你」即可。
EOF

# 4. 初始化 Git 备份（强烈推荐）
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "初始化 Agent workspace"

保密提醒

即使在私有仓库中，也不要在 workspace 中存放 API 密钥、OAuth token、密码等敏感信息。密钥等存放在 ~/.openclaw/ 目录或环境变量中。建议 .gitignore 中加入 .env、*.key、*.pem。

workspace 位置配置

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",  // 默认路径
    },
  },
}

• 环境变量 OPENCLAW_WORKSPACE_DIR 覆盖默认路径
• OPENCLAW_PROFILE 非 default 时，默认路径变为 ~/.openclaw/workspace-<profile>
• 多 Agent 场景下，每个 Agent 可有独立 workspace

经验：MEMORY.md 怎么写才高效

✅ 推荐写法

# 用户偏好
- 编程语言：TypeScript 优先，Python 备选
- 不喜欢用 class，偏好函数式
- 部署方式：Docker Compose，k3s 集群

# 项目环境
- 生产环境 k3s 集群 IP：192.168.1.x
- 数据库用 PostgreSQL 16，Redis 7
- CI/CD 用 GitHub Actions，镜像仓库用 ghcr.io

# 关键决策
- 2026-07：选型 React 19 + TanStack Router，放弃 Next.js（SSR 不需要）
- 2026-06：API 层用 Hono，替代 Express（性能更好）

❌ 避免的做法

• 📛 写成长篇日记 —— 放 memory/YYYY-MM-DD.md
• 📛 每天无差别追加 —— 精力收敛：合并、删旧、提炼
• 📛 把聊天记录贴进去 —— 这是 session transcript 的职责
• 📛 膨胀到超过 bootstrap 预算 —— 会被截断，反而丢失关键信息

维护节奏

Agent 会在 compaction（对话压缩）前自动执行 memory flush，把对话中的关键信息写入 memory 文件。建议每 1-2 周手动整理 MEMORY.md，将过时条目移到 memory/ 归档，保持主文件精简在 200 行以内。

下一步

理解了 workspace 结构后，继续学习 Skills 技能系统 →

加载练习题中...

---

🎯 本章要点

• MEMORY.md 存储精选长期记忆，会话启动时自动注入
• AGENTS.md、SOUL.md、USER.md、TOOLS.md 均在 Agent 启动时自动加载