Agent 工作区

Workspace（工作区）是 Agent 的文件系统上下文。Agent 通过工作区中的 Markdown 文件获取行为指令、人格定义、工具配置与持久化记忆。

默认位置

# 默认工作区路径
~/.openclaw/workspace/

自定义路径

可通过环境变量 OPENCLAW_WORKSPACE 或启动参数 --workspace 指定工作区路径。

目录结构

~/.openclaw/workspace/
├── AGENTS.md          # 智能体行为指令
├── SOUL.md            # 人格定义
├── TOOLS.md           # 工具定义
├── IDENTITY.md        # 身份信息
├── USER.md            # 用户画像
├── HEARTBEAT.md       # 心跳任务配置
├── BOOTSTRAP.md       # 引导上下文
├── MEMORY.md          # 长期记忆
├── skills/            # 工作区技能目录
│   ├── my-skill/
│   │   ├── SKILL.md
│   │   └── tool.sh
│   └── another-skill/
│       └── SKILL.md
├── hooks/             # 生命周期钩子
│   ├── on-message.sh
│   └── on-session-start.sh
└── memory/            # 每日记忆日志
    ├── 2025-01-15.md
    └── 2025-01-16.md

关键文件说明

AGENTS.md — 行为指令

定义 Agent 的核心行为规则和工作流程：

# Agent Instructions

You are a helpful assistant that specializes in code review.

## Rules
- Always explain your reasoning
- Use formal language
- Provide code examples when relevant

SOUL.md — 人格定义

定义 Agent 的个性特征与沟通风格：

# Personality

You are warm, professional, and concise.
You use analogies to explain complex topics.
You have a subtle sense of humor.

TOOLS.md — 工具定义

声明 Agent 可使用的自定义工具：

# Tools

## web_search
Search the web for current information.
- Input: query (string)
- Output: search results (JSON)

## file_read
Read a file from the workspace.
- Input: path (string)
- Output: file content (string)

IDENTITY.md — 身份信息

Agent 的名称与基本身份标识：

# Identity
Name: CodeBot
Role: Senior Code Reviewer
Organization: MyTeam

MEMORY.md — 长期记忆

存储经过整理的重要事实（仅在私聊中更新）：

# Long-term Memory

- User prefers TypeScript over JavaScript
- Project uses pnpm as package manager
- Deployment target: Vercel

技能目录（Skills Directory）

Skills（技能）是可复用的功能模块，分为三级加载：

Bundled Skills

# 内置技能，随 OpenClaw 发布
/app/skills/

Managed Skills

# 用户通过命令安装的技能
~/.openclaw/skills/

Workspace Skills

# 工作区本地技能
~/.openclaw/workspace/skills/

每个 Skill 目录结构：

my-skill/
├── SKILL.md       # 技能定义（必需）
├── tool.sh        # 工具脚本（可选）
├── tool.py        # Python 工具（可选）
└── README.md      # 说明文档（可选）

Hooks 目录

Hooks（钩子）在特定生命周期事件触发时执行：

hooks/
├── on-message.sh         # 收到消息时
├── on-session-start.sh   # 会话开始时
├── on-session-end.sh     # 会话结束时
└── on-agent-start.sh     # Agent 启动时

执行权限

Hook 脚本需要具有可执行权限。在 Linux/macOS 上需执行 chmod +x hooks/*.sh。

文件发现与加载顺序

Agent 启动时按以下顺序发现和加载文件：

1. AGENTS.md      → 最先加载，定义核心行为
2. SOUL.md        → 注入人格
3. TOOLS.md       → 注册工具
4. IDENTITY.md    → 设置身份
5. USER.md        → 加载用户画像
6. HEARTBEAT.md   → 配置心跳任务
7. BOOTSTRAP.md   → 注入引导上下文
8. MEMORY.md      → 加载长期记忆

Bootstrap 截断

每个 Bootstrap 文件受 bootstrapMaxChars 限制，所有文件总计受 bootstrapTotalMaxChars 限制。超出部分将被截断。

工作区隔离

多 Agent 场景下，每个 Agent 拥有独立的工作区：

~/.openclaw/
├── workspace/           # 默认 Agent 工作区
├── agents/
│   ├── coder/
│   │   └── workspace/   # coder Agent 的工作区
│   └── writer/
│       └── workspace/   # writer Agent 的工作区

• Agent 之间的工作区完全隔离
• 文件修改不会影响其他 Agent
• 会话状态和记忆独立存储

🇨🇳 中国用户须知

• 工作区文件完全支持中文内容
• 建议 SOUL.md 使用中文定义人格，提升中文对话质量
• 路径中避免使用中文字符，以防兼容性问题

下一步

• 了解 系统提示词 如何使用工作区文件
• 探索 记忆系统 的持久化机制
• 查看 功能总览 了解完整能力