OpenClaw Workspace

概述

Workspace（工作空间）是 OpenClaw Agent 的家目录，是文件工具和工作空间上下文的唯一工作目录。它不仅是存储配置的地方，更是 Agent 的记忆载体，包含了身份、用户信息、长期记忆等关键文件。

目录结构

核心文件

workspace/
├── SOUL.md               # Agent 的灵魂和个性
├── USER.md               # 用户信息和偏好
├── IDENTITY.md           # Agent 身份信息
├── AGENTS.md             # 工作空间配置和行为准则
├── MEMORY.md             # 长期记忆文件
├── TOOLS.md              # 本地工具配置
├── HEARTBEAT.md          # 心跳检查清单
├── BOOTSTRAP.md          # 初始设置文件（首次运行后删除）
├── memory/               # 每日记忆目录
│   ├── 2026-03-20.md   # 当天记忆
│   └── ...               # 其他日期记忆
└── skills/               # 自定义技能目录
    └── custom-skill/     # 自定义技能
        └── SKILL.md      # 技能元数据
        

文件用途说明

• SOUL.md： 定义 Agent 的核心个性、价值观和工作方式
• USER.md： 记录用户的偏好、习惯和需求
• IDENTITY.md： Agent 的基本信息（姓名、类型、风格等）
• AGENTS.md： 工作空间配置和行为准则
• MEMORY.md： 长期记忆，包含重要决策、上下文和知识
• TOOLS.md： 本地工具配置，如 API 密钥、服务地址等

工作空间管理

文件操作

Agent 可以在工作空间中进行各种文件操作：

# 读取文件
read("MEMORY.md")

# 写入文件
write("memory/2026-03-20.md", "今天完成了重要任务...")

# 编辑文件
edit("USER.md", oldText="旧内容", newText="新内容")

# 创建目录
exec("mkdir -p projects/my-project")
        

上下文注入

工作空间文件会被自动注入到 Agent 的上下文中：

• 主会话： 加载 SOUL.md、USER.md、MEMORY.md 等
• 子代理： 只加载 AGENTS.md 和 TOOLS.md
• 心跳检查： 只加载 HEARTBEAT.md

安全与权限

访问控制

• 相对路径： 相对于工作空间目录
• 绝对路径： 可以访问系统其他位置（需谨慎）
• 权限限制： 可以通过安全策略限制文件访问

最佳实践

• 将敏感信息存储在工作空间中
• 避免使用绝对路径访问系统文件
• 定期备份重要工作空间文件
• 使用 .gitignore 排除敏感文件

安全配置示例

# 安全策略配置
{
  "security": {
    "fileAccess": "workspace-only",
    "execCommands": ["read", "write", "edit"],
    "denyAbsolutePaths": true
  }
}
        

工作空间与配置目录的区别

工作空间 (Workspace)

• Agent 的家目录
• 包含身份、记忆、用户信息
• 用于文件工具和上下文
• 每个 Agent 有独立的工作空间

配置目录 (~/.openclaw/)

• 系统级配置存储
• 包含全局配置、凭证、会话
• 不用于文件工具
• 所有 Agent 共享

目录关系

~/.openclaw/                # 系统配置目录
├── config.json           # 全局配置
├── credentials/          # 凭证存储
├── sessions/             # 会话历史
└── agents/               # Agent 配置
    └── my-agent/         # 特定 Agent 配置
        └── workspace/    # ← 这就是工作空间
            ├── SOUL.md
            ├── USER.md
            └── ...
        

工作空间初始化

首次启动流程

1. 检查是否存在 BOOTSTRAP.md
2. 如果存在，执行初始设置对话
3. 收集 Agent 身份信息
4. 创建 SOUL.md、USER.md、IDENTITY.md
5. 删除 BOOTSTRAP.md
6. 开始正常运行

身份配置示例

# IDENTITY.md 示例
- **Name:** ClawAssistant
- **Creature:** AI Assistant
- **Vibe:** Helpful and efficient
- **Emoji:** 🦞
- **Avatar:** avatars/claw.png
        

记忆管理

长期记忆 (MEMORY.md)

包含重要的长期信息，如：

• 用户偏好和习惯
• 重要决策和上下文
• 项目状态和进度
• 联系人和关系网络

每日记忆 (memory/YYYY-MM-DD.md)

记录每天的具体活动和事件：

# memory/2026-03-20.md 示例
## 2026-03-20 活动记录

### 上午
- 处理了用户关于 OpenClaw 架构的问题
- 创建了 Gateway、Agent、Skill 等组件页面

### 下午  
- 测试了 GPT-5.4 模型连接
- 修复了网站 404 问题

### 晚上
- 完成了 OpenClaw 组件文档系统
        

最佳实践

工作空间组织

• 清晰的文件结构： 使用一致的命名约定
• 模块化设计： 将相关功能分组到子目录
• 版本控制： 使用 Git 管理工作空间变更
• 文档完善： 为复杂配置添加注释

性能优化

• 定期清理过时的记忆文件
• 优化大文件的读写操作
• 使用缓存减少重复文件访问
• 监控工作空间磁盘使用情况

常见问题

如何创建新工作空间？

# 创建新 Agent 工作空间
openclaw agents create my-new-agent
        

如何备份工作空间？

# 备份整个工作空间
cp -r ~/.openclaw/agents/my-agent/workspace ~/backup/

# 或使用 Git
cd ~/.openclaw/agents/my-agent/workspace
git init
git add .
git commit -m "Initial backup"
        

工作空间损坏怎么办？

可以从备份恢复，或者重新初始化工作空间。重要的是定期备份 MEMORY.md 和其他关键文件。