5.8 Agent工作区

核心概念核心概念

Agent 工作区是 OpenClaw 为代理提供的私有默认工作目录,用于文件工具操作和上下文管理,与 ~/.openclaw/ 配置目录是分开的。

核心概念

什么是工作区?

  • 私有目录: 代理的专属工作空间
  • 默认路径: ~/.openclaw/workspace
  • 文件工具基准: 所有文件操作的默认起点
  • 上下文来源: Bootstrap 文件、技能、记忆等的存储位置

与配置目录的区别

  • ~/.openclaw/: OpenClaw 的配置、日志、缓存
  • ~/.openclaw/workspace: 代理的工作区,包含 Bootstrap 文件和用户数据

工作区结构

~/.openclaw/workspace/
├── AGENTS.md              # 代理定义和配置
├── SOUL.md                # 代理核心价值观
├── USER.md                # 用户信息和偏好
├── IDENTITY.md            # 代理身份设定
├── TOOLS.md               # 自定义工具说明
├── HEARTBEAT.md           # 心跳配置
├── BOOT.md                # 启动脚本
├── BOOTSTRAP.md           # 通用 Bootstrap 内容
├── MEMORY.md              # 长期记忆摘要 (可选)
├── memory/                # 每日记忆文件
│   ├── 2026-02-01.md     # 今日记忆
│   ├── 2026-01-31.md     # 昨日记忆
│   └── ...
├── skills/                # 技能文件
│   ├── python-expert.md
│   ├── devops-guide.md
│   └── ...
└── canvas/                # 画布文件 (草稿、想法)
    ├── project-ideas.md
    └── ...

Bootstrap 文件

核心 Bootstrap 文件

AGENTS.md

定义代理的角色、权限和配置。

# My Agents

## Main Assistant
- Role: General-purpose coding assistant
- Permissions: Full workspace access
- Tools: All available

## Code Reviewer
- Role: Code review specialist
- Permissions: Read-only on main projects
- Tools: read, grep, git

SOUL.md

定义代理的核心价值观和行为准则。

# Agent Soul

## Core Values
- Always prioritize user privacy
- Be helpful, harmless, and honest
- Explain reasoning when making decisions

## Behavior Guidelines
- Ask for clarification when uncertain
- Provide context with code examples
- Respect existing code conventions

USER.md

存储用户偏好和上下文信息。

# User Profile

## Preferences
- Language: 中文
- Code style: Prettier + ESLint
- Timezone: Asia/Shanghai

## Context
- Working on: E-commerce platform
- Tech stack: Node.js, React, PostgreSQL
- Team size: 5 developers

IDENTITY.md

定义代理的身份和人格特征。

# Agent Identity

Name: CodeMaster
Personality: Professional, patient, detail-oriented
Expertise: Full-stack development, DevOps
Communication style: Clear, concise, with examples

文件处理规则

  • 截断限制: 单个文件最多注入 20,000 字符
  • 缺失文件: 缺失的文件会在系统提示词中显示"missing file"标记
  • 大文件警告: 超过限制的文件会被截断,建议保持精简

每日记忆系统

OpenClaw 自动管理 memory/ 目录中的每日记忆文件。

自动创建

memory/
├── 2026-02-01.md  # 今日记忆 (自动创建)
├── 2026-01-31.md  # 昨日记忆
└── 2026-01-30.md  # 前日记忆

记忆内容

每日记忆文件记录:

  • 当天的重要对话摘要
  • 完成的任务和决策
  • 需要记住的上下文
  • 用户反馈和偏好更新

MEMORY.md

可选的长期记忆摘要文件:

# Long-term Memory

## Recent Projects
- E-commerce platform: Completed authentication module
- API refactoring: In progress

## User Preferences Evolution
- Initial: Preferred verbose explanations
- Current: Prefers concise summaries with code

## Important Context
- Database migration planned for Q2
- New team member joining next month

技能管理

技能文件结构

skills/
├── python-expert.md       # Python 专家技能
├── devops-guide.md        # DevOps 指南
├── database-optimization.md
└── react-best-practices.md

技能文件示例

# Python Expert

## Expertise Areas
- Async programming (asyncio, trio)
- Performance optimization
- Testing (pytest, unittest)
- Package management (poetry, pip)

## Best Practices
- Use type hints for better code clarity
- Prefer pathlib over os.path
- Follow PEP 8 style guidelines

## Common Patterns
[Include reusable code patterns and examples]

按需加载

技能在系统提示词中只列出路径,模型需要时通过 read 工具加载完整内容,节省 token。

配置工作区

全局配置

{
  "workspace": {
    "path": "~/.openclaw/workspace",  // 默认路径
    "bootstrap": {
      "maxChars": 20000,              // 单个文件最大字符数
      "required": [                   // 必需的 Bootstrap 文件
        "AGENTS.md",
        "SOUL.md"
      ],
      "optional": [                   // 可选的 Bootstrap 文件
        "USER.md",
        "IDENTITY.md",
        "MEMORY.md"
      ]
    }
  }
}

代理级工作区

支持为不同代理配置不同的工作区:

{
  "agents": {
    "main-agent": {
      "workspace": "~/.openclaw/workspace"
    },
    "project-agent": {
      "workspace": "~/projects/ai-agent-workspace"
    }
  }
}

沙箱与工作区

非沙箱模式

默认情况下,工作区不是硬沙箱:

  • 代理可以访问工作区外的文件 (如果路径明确指定)
  • 工作区只是默认起点,不是严格限制

启用沙箱

{
  "agents": {
    "defaults": {
      "sandbox": true  // 启用沙箱,限制文件访问
    }
  }
}

启用沙箱后:

  • 代理只能访问工作区内的文件
  • 沙箱会话使用 ~/.openclaw/sandboxes/<session-id>
  • 提供更严格的安全隔离

工作区访问权限

{
  "agents": {
    "read-only-agent": {
      "workspaceAccess": "ro"  // 只读访问
    },
    "full-access-agent": {
      "workspaceAccess": "rw"  // 读写访问 (默认)
    },
    "no-access-agent": {
      "workspaceAccess": "none"  // 无访问权限,使用沙箱
    }
  }
}

工作区管理

初始化工作区

# 创建默认工作区结构
openclaw setup

# 指定自定义路径
openclaw setup --workspace ~/my-workspace

# 只创建缺失的文件
openclaw setup --workspace --safe

检查工作区状态

# 检查 Bootstrap 文件状态
openclaw setup --check

# 输出示例:
✓ AGENTS.md (1,234 chars)
✓ SOUL.md (856 chars)
✓ USER.md (432 chars)
✗ IDENTITY.md (missing)
⚠ MEMORY.md (23,456 chars - exceeds 20,000 limit)

迁移工作区

# 1. 克隆现有工作区到 Git 仓库
cd ~/.openclaw/workspace
git init
git add .
git commit -m "Initial workspace backup"

# 2. 推送到远程仓库
gh repo create my-openclaw-workspace --private
git push -u origin main

# 3. 在新机器上克隆
cd ~/.openclaw
git clone https://github.com/username/my-openclaw-workspace workspace

# 4. 更新配置指向新路径
openclaw config set workspace.path ~/.openclaw/workspace

安全最佳实践

重要安全提示
  • 保持私有: 工作区包含敏感信息,不要公开分享
  • 不提交密钥: 永远不要将 API Keys、Tokens、密码提交到 Git
  • 使用 .gitignore: 排除敏感文件和聊天历史
  • 定期备份: 使用私有 Git 仓库备份工作区

推荐的 .gitignore

# 敏感文件
*.key
*.pem
.env
credentials.json

# 聊天历史
*.jsonl
sessions/

# 临时文件
.DS_Store
*.tmp
*.log

备份工作区

Git 备份 (推荐)

# 初始化 Git 仓库
cd ~/.openclaw/workspace
git init

# 添加私有远程仓库
gh repo create my-workspace --private
git remote add origin https://github.com/username/my-workspace.git

# 提交并推送
git add .
git commit -m "Backup workspace"
git push -u origin main

# 自动备份 (可选: 添加到 crontab)
0 0 * * * cd ~/.openclaw/workspace && git add . && git commit -m "Auto backup" && git push

手动备份

# 创建压缩包
tar -czf workspace-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/workspace

# 恢复
tar -xzf workspace-backup-20260201.tar.gz -C ~/

多代理工作区

在多代理路由场景中,可以为不同代理配置独立工作区:

{
  "agents": {
    "code-agent": {
      "workspace": "~/.openclaw/workspaces/code-agent"
    },
    "docs-agent": {
      "workspace": "~/.openclaw/workspaces/docs-agent"
    },
    "devops-agent": {
      "workspace": "~/.openclaw/workspaces/devops-agent"
    }
  }
}

常用命令

# 初始化工作区
openclaw setup

# 检查工作区状态
openclaw setup --check

# 重新生成默认 Bootstrap 文件
openclaw setup --workspace

# 查看工作区路径
openclaw config get workspace.path

# 设置自定义工作区路径
openclaw config set workspace.path ~/my-workspace

# 列出 Bootstrap 文件
ls -lh ~/.openclaw/workspace/*.md

# 编辑 Bootstrap 文件
$EDITOR ~/.openclaw/workspace/SOUL.md

最佳实践

优化建议
  • 保持精简: Bootstrap 文件应简洁,避免超过 20,000 字符限制
  • 定期更新: 根据使用反馈更新 SOUL.md 和 USER.md
  • 结构化技能: 将技能文件组织成清晰的目录结构
  • 版本控制: 使用 Git 追踪 Bootstrap 文件的变化
  • 备份重要数据: 定期备份工作区到私有仓库
  • 隔离敏感信息: 使用环境变量或密钥管理工具存储敏感信息

相关概念