【OpenClaw】Workspace 配置完整指南

OpenClaw Workspace 配置完整指南

📋 目录

核心概念
默认位置与路径配置
Workspace 文件结构
配置方式
Git 备份与版本控制
安全与隔离
多 Agent 路由
最佳实践

核心概念

什么是 Workspace？

Workspace 是 Agent 的家，是 OpenClaw 用于文件工具和 workspace context 的唯一工作目录。

关键区分：

Workspace (~/.openclaw/workspace)：Agent 的工作目录，存储记忆、技能、配置等

Config (~/.openclaw/)：存储全局配置、凭证和会话数据

重要特性

特性	说明
默认工作目录	Workspace 是默认的 `cwd`，工具解析相对路径时基于此
非硬沙箱	不是严格的沙箱隔离，绝对路径仍可访问系统其他位置
私有记忆	应视为私有记忆，不要公开分享或提交到公开仓库
自动创建	运行 `openclaw onboard` 或 `openclaw setup` 时自动创建

默认位置与路径配置

默认路径

环境	默认路径
标准	`~/.openclaw/workspace`
多 Profile	`~/.openclaw/workspace-<profile>`（当 `OPENCLAW_PROFILE` 不为 `"default"` 时）

自定义路径

在 ~/.openclaw/openclaw.json 中配置：

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

初始化 Workspace

# 自动创建 workspace 并填充引导文件
openclaw onboard
# 或
openclaw setup
# 或
openclaw configure

💡 提示：如果 Workspace 不存在，这些命令会自动创建并填充引导文件。

Workspace 文件结构

核心引导文件

文件	用途	加载频率
`AGENTS.md`	Agent 操作指令和内存使用规则	每次会话开始
`SOUL.md`	人格、语气和边界定义	每次会话开始
`USER.md`	用户信息和称呼方式	每次会话开始
`IDENTITY.md`	Agent 名称、风格和 Emoji	每次会话开始
`TOOLS.md`	本地工具和约定说明（不控制工具可用性）	每次会话开始
`HEARTBEAT.md`	心跳检查的小型清单（保持简短）	心跳触发时
`BOOT.md`	可选的启动清单（网关重启时执行）	网关重启时
`BOOTSTRAP.md`	一次性首次运行仪式（完成后删除）	仅首次运行

记忆系统

文件/目录	用途	说明
`memory/YYYY-MM-DD.md`	每日记忆日志	每天一个文件，建议启动时读取今天和昨天的
`MEMORY.md`	策展的长期记忆	仅在主私有会话中加载，不适用于共享/群组上下文

扩展目录

目录	用途	说明
`skills/`	工作区专属技能	最高优先级技能位置，覆盖项目/个人/托管/内置技能
`canvas/`	Canvas UI 文件	节点显示文件（如 `canvas/index.html`）

引导文件限制

单个文件最大字符数：agents.defaults.bootstrapMaxChars（默认 20000）
总字符数限制：agents.defaults.bootstrapTotalMaxChars（默认 150000）
缺失文件处理：缺失的引导文件会注入”missing file”标记，会话继续

配置方式

1. 交互式向导

# 完整引导流程
openclaw onboard
 
# 配置向导
openclaw configure

2. CLI 命令

# 查询配置
openclaw config get agents.defaults.workspace
 
# 设置配置
openclaw config set agents.defaults.workspace "~/.openclaw/my-workspace"
 
# 删除配置
openclaw config unset agents.defaults.skipBootstrap

3. Control UI

访问 http://127.0.0.1:18789，使用 Config 标签页。

4. 直接编辑

直接编辑 ~/.openclaw/openclaw.json，网关会自动监视文件并应用更改。

Workspace 相关配置字段

基础配置

{
  agents: {
    defaults: {
      // Workspace 路径
      workspace: "~/.openclaw/workspace",
      
      // 跳过引导文件创建（如果自行管理）
      skipBootstrap: false,
      
      // 引导文件大小限制
      bootstrapMaxChars: 20000,
      bootstrapTotalMaxChars: 150000,
    },
  },
}

沙箱配置

{
  agents: {
    defaults: {
      sandbox: {
        // 沙箱模式：off | non-main | all
        mode: "non-main",
        
        // 沙箱范围：session | agent | shared
        scope: "agent",
        
        // 沙箱工作区根目录
        workspaceRoot: "~/.openclaw/sandboxes",
        
        // 工作区访问权限
        workspaceAccess: "rw",  // rw | ro | none
      },
    },
  },
}

⚠️ 注意：当启用沙箱且 workspaceAccess 不为 "rw" 时，工具操作在 ~/.openclaw/sandboxes 下的沙箱工作区中进行，而非主机工作区。

Git 备份与版本控制

为什么需要 Git 备份？

数据安全：Workspace 包含 Agent 的记忆和技能，丢失等于 Agent “失忆”
版本追踪：可回滚到之前的状态
迁移方便：在新机器上克隆仓库即可恢复

初始化 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"

添加远程仓库（GitHub/GitLab）

方式 A：GitHub Web UI

在 GitHub 创建新的私有仓库
不要初始化 README（避免合并冲突）
复制 HTTPS 远程 URL
执行：

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

方式 B：GitHub CLI (gh)

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

方式 C：GitLab Web UI

在 GitLab 创建新的私有仓库
不要初始化 README
复制 HTTPS 远程 URL
执行相同命令

日常更新

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

迁移到新机器

克隆仓库到目标路径（默认 ~/.openclaw/workspace）
在 ~/.openclaw/openclaw.json 中设置 agents.defaults.workspace
运行 openclaw setup --workspace <path> 补充缺失文件
如需会话数据，从旧机器复制 ~/.openclaw/agents/<agentId>/sessions/

安全与隔离

不要提交的秘密

即使在私有仓库中，也要避免在 Workspace 中存储：

❌ API Keys、OAuth Token、密码
❌ ~/.openclaw/ 目录下的任何内容
❌ 敏感聊天记录或附件

沙箱隔离

如果需要代码执行的严格隔离：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // 非主会话使用沙箱
        scope: "agent",
        workspaceAccess: "rw",
      },
    },
  },
}

构建沙箱镜像：

scripts/sandbox-setup.sh

多 Agent 路由

使用场景

工作和生活分离：不同的 Workspace 用于不同场景
多用户环境：每个用户使用独立的 Agent
项目隔离：不同项目使用不同的记忆和技能

配置示例

{
  agents: {
    list: [
      { 
        id: "home", 
        default: true, 
        workspace: "~/.openclaw/workspace-home" 
      },
      { 
        id: "work", 
        workspace: "~/.openclaw/workspace-work" 
      },
    ],
  },
  bindings: [
    { 
      agentId: "home", 
      match: { channel: "whatsapp", accountId: "personal" } 
    },
    { 
      agentId: "work", 
      match: { channel: "whatsapp", accountId: "biz" } 
    },
  ],
}

绑定规则

匹配条件	说明
`channel`	消息平台（whatsapp、telegram 等）
`accountId`	平台账号 ID
`peerId`	发送者 ID
`groupId`	群组 ID

配置热重载

重载模式

模式	行为
`hybrid`（默认）	热应用安全更改，自动重启处理关键更改
`hot`	仅热应用安全更改，记录需要重启的警告
`restart`	任何配置更改都重启网关
`off`	禁用文件监视，更改需手动重启

配置示例

{
  gateway: {
    reload: { 
      mode: "hybrid", 
      debounceMs: 300 
    },
  },
}

热应用 vs 需重启

类别	字段	需要重启？
渠道	`channels.*`, `web`	否
Agent 和模型	`agent`, `agents`, `models`, `routing`	否
自动化	`hooks`, `cron`, `agent.heartbeat`	否
会话和消息	`session`, `messages`	否
工具和媒体	`tools`, `browser`, `skills`, `audio`, `talk`	否
UI 和杂项	`ui`, `logging`, `identity`, `bindings`	否
网关服务器	`gateway.*`（端口、绑定、认证、TLS）	是
基础设施	`discovery`, `canvasHost`, `plugins`	是

环境变量

环境变量来源

OpenClaw 从以下位置读取环境变量（按优先级）：

父进程环境变量
当前工作目录的 .env（如果存在）
~/.openclaw/.env（全局回退）

在配置中引用环境变量

{
  gateway: { 
    auth: { 
      token: "${OPENCLAW_GATEWAY_TOKEN}" 
    } 
  },
  models: { 
    providers: { 
      custom: { 
        apiKey: "${CUSTOM_API_KEY}" 
      } 
    } 
  },
}

规则：

仅匹配大写名称：[A-Z_][A-Z0-9_]*
缺失/空变量会在加载时报错
转义：$${VAR} 输出字面值
在 $include 文件中也可用

Shell 环境导入

{
  env: {
    shellEnv: { 
      enabled: true, 
      timeoutMs: 15000 
    },
  },
}

或使用环境变量：OPENCLAW_LOAD_SHELL_ENV=1

最佳实践

1. 保持单一活跃 Workspace

多个 Workspace 目录会导致认证和状态混乱。建议：

仅保留一个活跃 Workspace
不再使用的旧目录归档或删除
使用 openclaw doctor 检测额外的 Workspace 目录

2. 定期 Git 备份

# 每日自动提交（可选 cron）
cd ~/.openclaw/workspace
git add . && git commit -m "Daily backup $(date +%Y-%m-%d)" && git push

3. 使用 Profile 管理多环境

# 设置 Profile
export OPENCLAW_PROFILE=work
 
# 此时 workspace 变为 ~/.openclaw/workspace-work

4. 监控 Workspace 大小

引导文件过大会增加 Token 消耗：

# 检查引导文件大小
du -sh ~/.openclaw/workspace/AGENTS.md
du -sh ~/.openclaw/workspace/memory/
 
# 清理旧记忆（可选）
find ~/.openclaw/workspace/memory/ -name "*.md" -mtime +90 -delete

5. 安全共享 Workspace

如需共享 Workspace（如团队协作）：

使用私有 Git 仓库
移除 MEMORY.md 和 memory/ 目录（包含个人记忆）
不提交 .env 和敏感文件
考虑使用 .gitattributes 过滤敏感内容

故障排查

常见问题

问题	解决方案
Workspace 未找到	运行 `openclaw setup --workspace <path>`
引导文件缺失	运行 `openclaw setup` 重建默认文件
配置验证失败	运行 `openclaw doctor` 查看详细错误
Git 冲突	手动解决冲突后重新提交
多 Workspace 警告	运行 `openclaw doctor` 检测并清理

诊断命令

# 检查系统状态
openclaw status
 
# 运行诊断
openclaw doctor
 
# 查看日志
openclaw logs
 
# 检查配置
openclaw config get agents.defaults.workspace

小M-Quartz

探索

【OpenClaw】Workspace 配置完整指南

📋 目录

核心概念

什么是 Workspace？

重要特性

默认位置与路径配置

默认路径

自定义路径

初始化 Workspace

Workspace 文件结构

核心引导文件

记忆系统

扩展目录

引导文件限制

配置方式

1. 交互式向导

2. CLI 命令

3. Control UI

4. 直接编辑

Workspace 相关配置字段

基础配置

沙箱配置

Git 备份与版本控制

为什么需要 Git 备份？

初始化 Git 仓库

添加远程仓库（GitHub/GitLab）

日常更新

迁移到新机器

安全与隔离

不要提交的秘密

推荐的 .gitignore

沙箱隔离

多 Agent 路由

使用场景

配置示例

绑定规则

配置热重载

重载模式

配置示例

热应用 vs 需重启

环境变量

环境变量来源

在配置中引用环境变量

Shell 环境导入

最佳实践

1. 保持单一活跃 Workspace

2. 定期 Git 备份

3. 使用 Profile 管理多环境

4. 监控 Workspace 大小

5. 安全共享 Workspace

故障排查

常见问题

诊断命令

相关资源

关系图谱

反向链接