基础

Agent 工作区

工作区是智能体的主目录。它是文件工具和工作区上下文使用的唯一工作目录。请保持其私密，并将它视为记忆。

这与 ~/.openclaw/ 是分开的，后者用于存储配置、凭据和会话。

默认位置

默认：~/.openclaw/workspace
如果设置了 OPENCLAW_PROFILE 且不是 "default"，默认值会变为 ~/.openclaw/workspace-<profile>。
在 ~/.openclaw/openclaw.json 中覆盖：

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}

openclaw onboard、openclaw configure 或 openclaw setup 会创建工作区，并在引导文件缺失时写入初始文件。

如果你已经自行管理工作区文件，可以禁用引导文件创建：

{ agents: { defaults: { skipBootstrap: true } } }

额外工作区文件夹

较早的安装可能创建了 ~/openclaw。保留多个工作区目录可能导致令人困惑的认证或状态漂移，因为同一时间只有一个工作区处于活动状态。

工作区文件映射

这些是 OpenClaw 期望在工作区内存在的标准文件：

AGENTS.md - operating instructions

智能体的操作说明，以及它应如何使用记忆。每个会话开始时都会加载。适合放置规则、优先级和“如何表现”的细节。

SOUL.md - persona and tone

人设、语气和边界。每个会话都会加载。指南：SOUL.md 个性指南。

USER.md - who the user is

用户是谁，以及如何称呼他们。每个会话都会加载。

IDENTITY.md - name, vibe, emoji

智能体的名称、风格和 emoji。在引导仪式期间创建/更新。

TOOLS.md - local tool conventions

关于你的本地工具和约定的说明。不控制工具可用性；仅作为指导。

HEARTBEAT.md - heartbeat checklist

Heartbeat 运行的可选小型检查清单。保持简短，避免消耗 token。

BOOT.md - startup checklist

Gateway 网关重启时自动运行的可选启动检查清单（启用内部钩子时）。保持简短；使用消息工具发送出站消息。

BOOTSTRAP.md - first-run ritual

一次性的首次运行仪式。仅为全新的工作区创建。仪式完成后将其删除。

memory/YYYY-MM-DD.md - daily memory log

每日记忆日志（每天一个文件）。建议在会话开始时读取今天和昨天的日志。

MEMORY.md - curated long-term memory (optional)

经整理的长期记忆。仅在主私密会话中加载（不要在共享/群组上下文中加载）。有关工作流和自动记忆刷新，请参见记忆。

skills/ - workspace skills (optional)

工作区专用 Skills。该工作区优先级最高的 Skills 位置。名称冲突时会覆盖项目智能体 Skills、个人智能体 Skills、托管 Skills、内置 Skills 和 skills.load.extraDirs。

canvas/ - Canvas UI files (optional)

用于节点显示的 Canvas UI 文件（例如 canvas/index.html）。

工作区中不包含什么

以下内容位于 ~/.openclaw/ 下，不应提交到工作区仓库：

~/.openclaw/openclaw.json（配置）
~/.openclaw/agents/<agentId>/agent/auth-profiles.json（模型认证配置文件：OAuth + API key）
~/.openclaw/agents/<agentId>/agent/codex-home/（每个智能体的 Codex 运行时账号、配置、Skills、插件和原生线程状态）
~/.openclaw/credentials/（渠道/提供商状态以及旧版 OAuth 导入数据）
~/.openclaw/agents/<agentId>/sessions/（会话转录 + 元数据）
~/.openclaw/skills/（托管 Skills）

如果你需要迁移会话或配置，请单独复制它们，并让它们保持在版本控制之外。

Git 备份（推荐，私有）

将工作区视为私有记忆。把它放进一个私有 git 仓库，以便备份和恢复。

在运行 Gateway 网关的机器上执行这些步骤（工作区就在那台机器上）。

Initialize the repo

如果安装了 git，全新的工作区会自动初始化。如果此工作区还不是仓库，请运行：

cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"

Add a private remote

GitHub web UI

在 GitHub 上创建一个新的私有仓库。
不要用 README 初始化（避免合并冲突）。
复制 HTTPS 远程 URL。
添加远程仓库并推送：

git branch -M main
git remote add origin <https-url>
git push -u origin main

GitHub CLI (gh)

gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push

GitLab web UI

在 GitLab 上创建一个新的私有仓库。
不要用 README 初始化（避免合并冲突）。
复制 HTTPS 远程 URL。
添加远程仓库并推送：

git branch -M main
git remote add origin <https-url>
git push -u origin main

Ongoing updates

git status
git add .
git commit -m "Update memory"
git push

不要提交密钥

建议的 .gitignore 初始内容：

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

将工作区移动到新机器

Clone the repo

将仓库克隆到目标路径（默认 ~/.openclaw/workspace）。

Update config

在 ~/.openclaw/openclaw.json 中将 agents.defaults.workspace 设置为该路径。

Seed missing files

运行 openclaw setup --workspace <path> 以填充任何缺失文件。

Copy sessions (optional)

如果你需要会话，请从旧机器单独复制 ~/.openclaw/agents/<agentId>/sessions/。

高级说明

多智能体路由可以为每个智能体使用不同工作区。有关路由配置，请参见渠道路由。
如果启用了 agents.defaults.sandbox，非主会话可以使用 agents.defaults.sandbox.workspaceRoot 下的每会话沙箱工作区。

Agent 工作区

默认位置

额外工作区文件夹

工作区文件映射

工作区中不包含什么

Git 备份（推荐，私有）

Initialize the repo

Add a private remote

GitHub web UI

GitHub CLI (gh)

GitLab web UI

Ongoing updates

不要提交密钥

将工作区移动到新机器

Clone the repo

Update config

Seed missing files

Copy sessions (optional)

高级说明

相关

Ask OpenClaw

# 默认位置

# 额外工作区文件夹

# 工作区文件映射

# 工作区中不包含什么

# Git 备份（推荐，私有）

Initialize the repo

Add a private remote

GitHub web UI

GitHub CLI (gh)

GitLab web UI

Ongoing updates

# 不要提交密钥

# 将工作区移动到新机器

Clone the repo

Update config

Seed missing files

Copy sessions (optional)

# 高级说明

# 相关

默认位置

额外工作区文件夹

工作区文件映射

工作区中不包含什么

Git 备份（推荐，私有）

不要提交密钥

将工作区移动到新机器

高级说明

相关