Workspace（工作区）是 Agent 的「家」——所有文件工具的工作目录、记忆文件、技能和上下文都在这里。理解工作区结构对于管理 AI Agent 的长期记忆和个性至关重要。
核心概念
- 工作区是 Agent 的默认工作目录，不是硬沙箱
- 文件工具（read/write/edit）的相对路径以工作区为基准
- 绝对路径仍可访问主机上的其他位置（启用沙箱可隔离）
- 工作区与
~/.openclaw/（配置、凭证）是分开的两个目录
默认位置
~/.openclaw/workspace
如果设置了 OPENCLAW_PROFILE（且不是 default），默认变为：
~/.openclaw/workspace-<profile>
自定义路径（在 openclaw.json 中）：
json
{
"agent": {
"workspace": "~/my-agent-workspace"
}
}工作区文件完整说明
| 文件 | 作用 | 加载时机 |
|---|---|---|
AGENTS.md | Agent 操作指南、规则和优先级 | 每次 Session 启动 |
SOUL.md | 人格、语气和边界 | 每次 Session 启动 |
USER.md | 用户信息和沟通偏好 | 每次 Session 启动 |
IDENTITY.md | Agent 名称、个性、emoji | 引导期间创建/更新 |
TOOLS.md | 本地工具注记（不控制可用性） | 每次 Session 启动 |
HEARTBEAT.md | 心跳运行的简短检查清单 | 心跳时读取 |
BOOT.md | Gateway 重启时执行的启动清单 | Gateway 启动时（需启用 boot-md hook） |
BOOTSTRAP.md | 首次运行仪式（完成后删除） | 仅新工作区 |
memory/YYYY-MM-DD.md | 每日记忆日志 | Session 启动时读今天+昨天 |
MEMORY.md | 精华长期记忆 | 仅主私人 Session |
skills/ | 工作区专属技能（覆盖同名 Skill） | Skill 发现时 |
canvas/ | Canvas UI 文件（如 index.html） | Node Canvas 展示时 |
什么不在工作区
以下内容在 ~/.openclaw/，不要提交到工作区 Git 仓库：
~/.openclaw/openclaw.json（主配置）~/.openclaw/credentials/（OAuth Token、API Key）~/.openclaw/agents/<agentId>/sessions/（会话记录）~/.openclaw/skills/（托管技能）
Git 备份（强烈推荐）
工作区是 Agent 的私人记忆，建议用私有 Git 仓库备份。
第一步：初始化仓库
bash
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "初始化 Agent 工作区"品牌新工作区会自动初始化 Git（如果 git 已安装）。
第二步：添加私有远程仓库
方案 A：GitHub 网页操作
- 创建一个私有仓库（不要初始化 README）
- 复制 HTTPS 地址
bash
git branch -M main
git remote add origin https://github.com/yourname/openclaw-workspace.git
git push -u origin main方案 B：GitHub CLI（更简单）
bash
gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push方案 C：GitLab
与 GitHub 类似，创建私有仓库后 push。
第三步：日常更新
bash
git status
git add .
git commit -m "更新记忆"
git push也可以让 Agent 在心跳时自动提交：
markdown
# HEARTBEAT.md
- 检查 memory/ 有没有新内容，有的话 git add + commit + push安全注意：绝对不要提交的内容
即使是私有仓库，也避免存储：
- API Key、OAuth Token、密码
~/.openclaw/下的任何文件- 敏感对话原文
推荐 .gitignore：
.DS_Store
.env
**/*.key
**/*.pem
**/secrets*
迁移到新机器
bash
# 1. 克隆仓库到目标路径
git clone https://github.com/yourname/openclaw-workspace.git ~/.openclaw/workspace
# 2. 设置工作区路径
openclaw config set agent.workspace ~/.openclaw/workspace
# 3. 补全缺失的引导文件
openclaw setup --workspace ~/.openclaw/workspace
# 4. 如需迁移历史 Session（可选）
# 从旧机器复制：~/.openclaw/agents/<agentId>/sessions/多 Agent 工作区
不同 Agent 使用不同工作区：
json
{
"agents": {
"list": [
{ "id": "personal", "workspace": "~/.openclaw/workspace-personal" },
{ "id": "work", "workspace": "~/.openclaw/workspace-work" }
]
}
}引导文件大小限制
- 单个文件最大：
agents.defaults.bootstrapMaxChars（默认 20000 字符） - 所有文件总计：
agents.defaults.bootstrapTotalMaxChars（默认 150000 字符）
文件过大会被截断注入，建议保持核心文件简洁。
原文：Agent Workspace - OpenClaw | 来源：OpenClaw 官方文档