第3课：Workspace配置体系【读懂OpenClaw的“大脑”】

Thomas_Sir
0 阅读14分钟

正文.png

上一节课，你成功跑通了第一个OpenClaw Agent——在终端看到了那行绿色的启动日志，在WebChat里收到了第一条AI回复。那一刻，你一定感受到了“让AI替你做事”带来的震撼。

但你可能也注意到一个现象：每次启动OpenClaw，它似乎都像第一次认识你。你上次告诉它的偏好，这次它又忘了；你希望它用简洁风格回复，它却总是长篇大论；你想让它扮演客服角色，它却老用私人助理的语气。

很多人装了满满一堆Skills，却觉得OpenClaw还是“一问一答”的傻白甜。别急着怪大模型变笨，也别急着骂Skills没用。真正的问题在于：你从来没有认真配置过那几个藏在工作区深处的关键文件。

没有配置Workspace，OpenClaw就是一个会调用工具的聊天机器人——每次对话都是全新的，没有记忆，没有性格，不知道你是谁，不知道你想要什么。配好Workspace，它才开始变成你的数字分身——记得你的偏好，知道自己的边界，能主动干活。

OpenClaw的核心秘密只有一个：一切皆Markdown。没有复杂的提示词编译器，没有黑盒——一组精心设计的Markdown文件在每次对话时被动态组装成系统提示词，赋予Agent人格、记忆、技能和行为准则。AGENTS.md、SOUL.md、USER.md、TOOLS.md、HEARTBEAT.md这些文件分别定义了Agent的启动逻辑、人格特质、服务对象、工具清单与自动化任务，是决定Agent工作效率的关键。

本节课，我们将系统性地深入Workspace目录，读懂每一个配置文件，理解OpenClaw如何“思考”，最终亲手配置一个专属智能客服Agent。

3.1 Workspace目录结构详解

一句话概括：Workspace是OpenClaw的“大脑所在地”——所有定义AI身份、规则、记忆和行为的Markdown文件都存放在这里，每次会话启动时被动态加载到系统提示词中。

在OpenClaw的世界里，Workspace（工作区） 是整个系统的核心状态目录。OpenClaw使用单个智能体工作区目录作为智能体工具和上下文的唯一工作目录（cwd）。默认情况下，这个目录位于~/.openclaw/workspace/。

理解Workspace的结构，是读懂OpenClaw“大脑”的第一步。以下是2026年社区通用的完整目录结构：

~/.openclaw/workspace/
├── AGENTS.md              # 代理调度规则与标准作业程序
├── BOOTSTRAP.md           # 初始化序列与核心系统提示词（首次运行后自动删除）
├── HEARTBEAT.md           # 定时执行逻辑与主动任务状态自检
├── IDENTITY.md            # 代理身份定义与系统边界约束
├── MEMORY.md              # 长期上下文数据与既定规则的持久化存储
├── SOUL.md                # 响应语气、行为特征及输出格式配置
├── TOOLS.md               # 工具授权注册表及调用参数规范
├── USER.md                # 用户画像数据，包含特定偏好与交互限制配置
├── memory/                # 日常运行日志与短期上下文存储
│   └── YYYY-MM-DD.md      # 按日期归档的会话记忆文件
├── skills/                # 已安装的第三方技能扩展目录
├── data/                  # 输入数据：表格、文本、爬虫结果
├── output/                # AI输出：报告、代码、脚本、markdown
├── workflows/             # 工作流定义目录（yml/json统一存放）
├── logs/                  # 运行日志、任务日志、错误日志
├── temp/                  # 临时文件，自动清理
└── assets/                # 静态资源：图片、模板、prompt模板

【重要提醒】：所有配置文件都是纯文本Markdown格式，可以用任何文本编辑器修改。修改后无需重启Gateway即可生效——OpenClaw在每次会话启动时会重新读取这些文件。但部分核心配置（如openclaw.json）修改后需要执行openclaw gateway restart。

六个核心文件，六种“大脑能力”

这六个文件各有分工，决定了AI的完整人格：

  • AGENTS.md（运行指令） ：定义AI的执行流程、决策边界和安全红线。
  • SOUL.md（人格灵魂） ：注入AI的性格、价值观和沟通风格。
  • USER.md（用户画像） ：记录用户是谁、偏好什么、习惯什么。
  • IDENTITY.md（自我认知） ：定义AI的名字、角色定位。
  • HEARTBEAT.md（定时任务） ：配置后台自动执行的周期性任务。
  • TOOLS.md（工具使用指南） ：描述环境中可用的工具及其使用惯例。

【避坑指南】：不要在工作区根目录下随意创建无关文件。OpenClaw会扫描整个workspace目录的Markdown文件并尝试注入提示词。无关文件会浪费Token且可能产生意外行为。建议将所有非配置文件移入data/或output/子目录。

如何查看和编辑这些文件？

有两种方式可以访问你的Workspace文件：

方式一：命令行方式

# 查看工作空间下的文件
ls -la ~/.openclaw/workspace/

# 进入工作空间目录
cd ~/.openclaw/workspace/

# 用vim/nano编辑
nano AGENTS.md

方式二：WebUI方式

访问http://localhost:18789/overview，点击“连接”，左侧选择“代理”->当前Agent，即可点击对应的md文件进行在线修改。

Workspace的创建与初始化

如果~/.openclaw/workspace/目录不存在，OpenClaw会在首次启动时自动创建。你也可以手动初始化：

# 使用openclaw setup命令初始化工作区
openclaw setup

# 指定自定义工作区路径
openclaw setup --workspace /path/to/custom/workspace

openclaw setup会创建一个安全的默认模板，包括AGENTS.md、SOUL.md、TOOLS.md等基本文件的默认版本。

3.2 AGENTS.md：定义Agent的角色与个性

一句话概括：AGENTS.md是OpenClaw的“操作手册”——它规定了AI的行为边界、安全红线、执行规范和记忆加载流程，是确保Agent“不乱来”的核心配置文件。

如果说OpenClaw是一个数字员工，那AGENTS.md就是这个员工的岗位职责说明书和员工手册。它不定义AI的性格（那是SOUL.md的事），也不定义AI的身份（那是IDENTITY.md的事），而是定义：在什么情况下做什么事、什么绝对不能做、遇到问题怎么处理。

AGENTS.md在每次会话启动时被加载，且优先级最高——它的指令会覆盖其他配置文件中的冲突内容。

AGENTS.md的核心配置模板

一个完整的AGENTS.md应该包含以下关键部分：

# AGENTS.md - 智能体启动与运行规则

## First Run（首次启动专属）
- 检测BOOTSTRAP.md是否存在，存在则优先执行（包含首次配置、依赖安装等）
- 执行完毕后自动删除BOOTSTRAP.md，避免重复初始化

## Session Startup（每次启动必执行）
1. 加载SOUL.md → 确认人格特质与行为边界
2. 加载USER.md → 读取用户画像与服务偏好
3. 加载memory/$(date +%Y-%m-%d).md → 获取当日上下文记忆
4. 主会话场景（如一对一沟通）额外加载MEMORY.md → 调用长期核心记忆
5. 加载TOOLS.md → 初始化可用工具与API配置
6. 注册HEARTBEAT.md → 启动定时任务检查

## 安全红线（Safety Defaults）
- Don't dump directories or secrets into chat.
- Don't run destructive commands unless explicitly asked.
- 禁止删除 .env、*.key、*.json 配置文件
- 禁止未经确认执行 rm -rf、格式化磁盘等危险命令
- 文件删除前必须询问用户确认

## 执行规范（Operation Standards）
1. 修改代码前必须先查看文件完整内容
2. 修改完成后必须执行相关测试验证
3. 遇到环境错误优先使用 `openclaw doctor` 诊断
4. 不确定的情况，先问再做

## 记忆系统规则（Memory Rules）
- Write it down — No "Mental Notes"!
- "Mental notes" don't survive session restarts. Files do.
- 用户说"记住这个" → 更新 memory/YYYY-MM-DD.md
- 重大决策、偏好变更 → 写入 MEMORY.md
- 会话启动时，读取今日+昨日记忆 + MEMORY.md（如有）

## 共享空间规范（Shared Spaces）
- 你在群聊或公共渠道中不是用户的代言人
- 不要分享私人数据、联系信息或内部笔记

AGENTS.md的实战配置技巧

AGENTS.md的配置直接影响Agent的工作效率。以下是几个经过验证的最佳实践：

技巧一：分层记忆加载

记忆类型存储位置加载时机效果
日常琐事memory/YYYY-MM-DD.md每次会话Token消耗低
重要经验MEMORY.md仅主会话防止敏感信息泄露
项目专项memory/project_*.md仅相关会话保持上下文聚焦

技巧二：安全边界的精确描述

模糊的安全指令无效。下面是对比：

❌ 错误做法：
"谨慎操作，注意安全，不要随便删除文件。"

✅ 正确做法：
"1. 执行任何写入操作前必须先向用户确认
2. 禁止删除任何文件（如需删除，改为移动到~/Trash目录）
3. 禁止执行包含'rm -rf'或'format'的命令"

越具体，Agent的响应越确定。

技巧三：禁止“脑内记忆”

AGENTS.md的默认模板中有一条至关重要的指令："Memory is limited — if you want to remember something, WRITE IT TO A FILE. 'Mental notes' don't survive session restarts. Files do."

这意味着：AI不能在对话中“在心里记下”任何信息。想让AI记住什么，就必须让它写入文件。

【避坑指南】：AGENTS.md不是一次配置就可以一劳永逸的。随着你对AI的使用深入，会发现新的边界和规范需求。建议每次遇到“AI做了你不希望它做的事”时，立即更新AGENTS.md添加对应规则。

3.3 TOOLS.md：声明AI可用工具的元数据

一句话概括：TOOLS.md不控制哪些工具可用——它只是告诉AI在你的环境中这些工具应该如何被使用。

这是整个Workspace配置体系中最容易被误解的文件，也是需要先澄清的第一个概念。

官方文档明确指出：TOOLS.md does NOT control which tools exist; it’s guidance for how you want them used。换言之，OpenClaw的核心工具（read、exec、edit、write以及系统工具）始终可用，TOOLS.md提供的是关于你希望AI如何使用这些工具的指导。

TOOLS.md的核心用途

TOOLS.md可以包含以下内容：

环境特定笔记（Notes for Skills） ：为每个技能标注在你的环境中的使用注意事项。

设备与平台信息：当前环境的操作系统、网络配置、SSH主机等。

API调用约定：各外部API的端点地址、认证方式、速率限制。

工具使用惯例：例如“优先使用write工具而非exec”、“文件操作使用工作区相对路径”等。

TOOLS.md配置示例

# TOOLS.md - 工具使用指南

## 环境信息
- OS: macOS Sequoia 15.4 (ARM64)
- Shell: zsh
- Workspace: ~/.openclaw/workspace/

## 文件操作惯例
- 优先使用 write 和 edit 工具进行文件修改
- exec 工具仅用于线性 shell 命令，不要嵌套复杂逻辑
- 所有文件路径使用相对于 workspace 的相对路径

## 可用技能及使用提醒
### filesystem (文件系统)
- 注意：禁止操作 /etc、/usr/bin 等系统目录
- 大文件读取使用 tail/head 限制行数

### browser (浏览器控制)
- 默认使用 headless 模式
- 需要登录的网站，登录凭证存储于 ~/.openclaw/secrets/

### imsg (iMessage)
- 发送消息前确认接收方为预期联系人
- 不在群聊中自动回复

## API端点
- 内部API: http://10.0.0.1:8080 (需要API Key)
- 企业微信机器人: webhook详见 ~/.openclaw/secrets/qywx/

## 网络约束
- 外网访问需要代理，代理配置见环境变量

TOOLS.md的加载机制

TOOLS.md与AGENTS.md、SOUL.md等文件一样，在每次会话启动时被注入系统提示词。但有一个关键区别：它不会像技能（Skills）的SKILL.md那样在需要时动态加载，而是始终存在于上下文中。因此，TOOLS.md应保持简洁，仅记录基础设施层面的信息，不要写入长篇技术文档。

【避坑指南】：不要把敏感信息（API Key、Token、密码）直接写在TOOLS.md中。这些信息应该存放在~/.openclaw/secrets/或环境变量中，TOOLS.md只引用它们。这与Git版本控制的安全实践一脉相承——敏感信息永远不入库。

3.4 SOUL.md：赋予AI独特的“人格”与风格

一句话概括：SOUL.md是AI的“灵魂”——它定义了Agent的沟通风格、表达方式、价值取向和情绪底色，赋予AI独一无二的语言个性。

一个OpenClaw实例可能拥有完全相同的工具集和模型，但配置了不同SOUL.md的两个Agent，说出的话可能判若两人。SOUL.md正是这种差异的唯一来源。

官方文档的定义是：SOUL.md defines identity, tone, and boundaries. 它决定了AI在每次回应时的身份、语气和边界。

SOUL.md应该包含的内容

一个好的SOUL.md，需要包含以下几个层面：

1. 核心身份与人格

明确告诉AI“你是谁”、“你是什么样的助手”：

## 核心身份
- 角色设定：你是用户的专属AI助手，专注于提高工作效率
- 专业领域：编程辅助、系统运维、文档处理
- 价值主张：能直接干的活儿直接干，拒绝废话

2. 沟通风格

这是AI“人味儿”的来源：

## 沟通风格
- 简洁直接，不废话，不客套
- 遇到问题先给结论，再解释原因
- 不用感叹号
- 不用“非常”“极其”“超级”等夸张词
- 技术术语保留英文，关键结论用加粗
- 不在每条回复末尾加“如有需要请随时告知”

3. 核心价值观与行为边界

## 核心价值观
- 效率优先：能自动化的事不手动做
- 结果导向：关注输出，不关注过程
- 诚实：不确定的事情直说不确定，不编造

## 绝对红线
- 隐私与边界：绝对禁止泄露任何项目代码或个人隐私
- 风险阻断：高危操作前必须请求确认并等待用户批准
- 懂就问：绝不靠幻觉瞎编证据或不存在的事实

4. 长期指令（生存法则）

## 长期指令
- 记忆连续性：每次响应前先读取今日记忆文件
- 生物钟感知：深夜时段（23:00-07:00）降低主动输出频率
- 版本意识：保持身份版本号，更新SOUL.md时主动告知用户

SOUL.md的最佳实践

原则一：具体优于抽象

模糊的指令如“要有帮助”会产生模糊的行为，而“最多输出5个要点，确认后再执行任何文件删除操作”会产生极其确定的行为。

原则二：少即是多

OpenClaw的系统提示词有Token限制——单个文件最大约20,000字符，总计约150,000字符。SOUL.md不必冗长，抓住核心人格特质即可。

原则三：随需迭代

SOUL.md不是一成不变的。你会发现模型的行为在迭代。不需要一步追求完美，可以在后续持续打磨。

【避坑指南】：很多用户的SOUL.md写得像公司使命宣言，充满大词空话。高质量SOUL.md应该更像“口述的性格罗盘”，指导Agent的微观选择。

示例对比

❌ 模糊版：
“我是一个乐于助人、专业可靠的AI助手。”

✅ 具体版：
“1. 先抛出核心结论，再用分点解释过程。
2. 不主动建议额外服务，除非用户明确询问。
3. 每个回答只输出最少必要字数。”

3.5 配置文件的全量注入机制与运行原理

一句话概括：OpenClaw的运行原理可以浓缩为一句话——每次对话启动时，把磁盘上的Markdown文件聚合成一个巨大的提示词，一次性塞给大模型，然后模型就拥有了一套完整的人格、规则和知识。

这是OpenClaw架构设计中最精妙也最关键的一环。理解了注入机制，就理解了OpenClaw的“思考原理”。

注入时机

OpenClaw在每次Agent运行时（即每次会话启动时）扫描workspace目录，将一组Markdown文件自动注入到系统提示词中。这个过程由resolveBootstrapContextForRun()函数编排，它会读取工作区文件、应用限制并处理截断警告。

OpenClaw的系统提示词被分成几个清晰的固定部分，按顺序拼接：

1. Tooling — 可用的工具列表
2. Safety — 简短的安全提醒
3. Skills — XML格式的技能列表
4. Workspace — 工作目录路径
5. Workspace Files (injected) — 注入的引导文件
6. Current Date & Time — 用户时区
7. Runtime — 主机、OS、Node版本、模型、仓库根目录

其中最关键的是第5部分：Workspace Files (injected) 。注入的文件列表如下：

文件用途
AGENTS.md操作指令和记忆
SOUL.md人格、边界、语气
TOOLS.md工具使用笔记和约定
IDENTITY.md代理名字、风格、emoji
USER.md你的资料和称呼偏好
HEARTBEAT.md定时任务配置
BOOTSTRAP.md首次运行时仪式（完成后删除）
MEMORY.md长期记忆

Token限制与内容截断

OpenClaw不会无限制地把所有内容都塞进提示词。系统内置了两个关键限制：

  • 单个文件最多agents.defaults.bootstrapMaxChars（默认20,000字符）
  • 所有注入内容总和最多agents.defaults.bootstrapTotalMaxChars（默认150,000字符）

这意味着：如果你的AGENTS.md写得超过2万字，超出的部分不会被注入。如果你的workspace总计超过15万字符，后续文件会被截断。控制提示词长度不仅能保证关键提示被完整注入，也能显著降低推理Token消耗。

记忆文件的特殊处理

需要特别注意的是：memory/目录下的每日记忆文件（如memory/2026-05-05.md）不会自动注入系统提示词。

OpenClaw的设计理念是：自动注入阶段只加载最稳定的文件——AGENTS.md、SOUL.md、USER.md等配置文件，它们定义了Agent的核心人格和规则。而动态生成的记忆内容，必须通过memory_search或工具显式按需读取。

# AGENTS.md中的正确记忆加载模式
- On session start, read today + yesterday + MEMORY.md when present.
- Use memory_get to retrieve specific memory files when needed.
- Do not dump entire memory/ into context.

提示词模式（Prompt Modes）

OpenClaw支持三种提示词模式，默认使用full模式：

模式描述适用场景
full完整模式，包含所有内容主会话、普通对话
minimal精简模式，去除Skills、Self-Update等子代理（sub-agents），节省Token
none只返回身份描述极端节省Token场景

在minimal模式下，只注入AGENTS.md和TOOLS.md，其他文件全部过滤掉——这样能大幅节省Token消耗。

【避坑指南】：如果发现Agent不回应某些内容、或“忘记”了你配置在SOUL.md里的角色定义，优先检查文件大小是否超标。很多看似配置不起作用的原因，就是写得太长了。

3.6 配置文件的版本管理（Git集成）

一句话概括：把Workspace纳入Git版本控制，是OpenClaw从“临时玩具”变成“核心生产力工具”的分水岭。

OpenClaw的配置文件体系本质上是一组文本文件。而凡是文本文件，就适合用Git来管理。官方文档明确建议：If you treat this workspace as Clawd's 'memory', make it a git repo (ideally private)。

没有版本控制的配置文件管理，仿佛在没有备份的情况下运行生产服务器。一旦某个配置被错误修改导致AI出现异常，没有历史记录就无从追溯，更无法回滚。而当AI的行为日志累积到难以管理的地步时，没有Git工作流就意味着混乱。

初始化Workspace的Git仓库

# 进入工作区
cd ~/.openclaw/workspace

# 初始化Git仓库
git init

# 创建.gitignore（核心安全步骤）
cat > .gitignore << 'EOF'
# 敏感信息目录
secrets/
.env
*.key
*.pem

# 运行时生成的日志和临时文件
logs/
temp/
*.log
*.jsonl

# 会话转录（包含对话历史，可能泄漏隐私）
sessions/
*.jsonl

# 本地配置文件覆盖（不同环境差异）
config.local.json
EOF

# 添加配置文件到暂存区
git add AGENTS.md SOUL.md USER.md IDENTITY.md TOOLS.md HEARTBEAT.md .gitignore

# 首次提交
git commit -m "Initial OpenClaw workspace configuration"

敏感信息保护：三条红线

红线一：永远不把API Key提交到Git仓库

# 错误做法
AGENTS.md: "使用API Key: sk-abc123xyz"

# 正确做法
TOOLS.md: "API Key存储在环境变量 BAILIAN_API_KEY 中"

所有API Key、Token、密码应当存放在：

  • 环境变量（如.env文件，并将.env加入.gitignore）
  • 系统密钥链（macOS Keychain / Windows Credential Manager）
  • 或专业的密钥管理服务（如Vault、AWS Secrets Manager）

红线二：.gitignore要严

上述示例中的.gitignore是一个良好的起点，但请根据你的实际部署情况进行完善。特别是secrets/目录和.env文件，必须严格忽略。

红线三：不要忘记分离数据与配置

memory/YYYY-MM-DD.md包含对话记忆，是否纳入版本控制取决于你的隐私需求。对于包含敏感客户信息的内容，建议不入库；但对于个人的工作日志，纳入版本控制可以让你追溯AI的“成长历程”。

Git工作流进阶

OpenClaw社区已经开始探索更高级的Git工作流。例如，利用Git worktree功能，Skill可以在隔离环境中进行功能开发、依赖安装和构建，而不污染主项目目录；它确保每个新任务都从干净、经验证的状态开始。

【避坑指南】.gitignore只能忽略那些原来没有被track的文件。如果某些敏感文件已经被纳入了版本管理中，则修改.gitignore是无效的——你需要先用git rm --cached <file>将其从Git索引中移除。

3.7 实战：编写一个客服Agent的配置文件

一句话概括：通过前面的学习，你已经理解了每个配置文件的作用——现在我们把它们组合起来，用30分钟配置一个真实可用的电商客服Agent，让它回答产品咨询、处理退换货流程、记录客户偏好。

这套客服Agent配置的核心设计原则是：让AI扮演“受管控的服务提供者”，而非“拥有系统全权的个人助手”。

这在安全层面有根本性差异——面向客户的Agent必须从“助手模式”切换到“服务模式”：

  • 个人助手模式：一个Gateway实例 = 一个信任边界，Agent默认有命令执行、文件读写、浏览器控制等完整权限
  • 客服服务模式：取消不必要的系统工具，只保留回答产品问题和访问知识库的权限

以下配置将按照“最小权限”原则构建。

Step 1：定义Agent的工作指南（AGENTS.md）

# AGENTS.md - 电商客服智能体工作规则

## First Run（首次启动）
- 检测BOOTSTRAP.md是否存在，存在则执行（初始化产品知识库、FAQ模板）
- 执行完毕后自动删除BOOTSTRAP.md

## Session Startup（每次会话启动）
1. 加载SOUL.md → 确认客服身份与沟通风格
2. 加载USER.md → 读取客户档案（如有历史记录）
3. 加载memory/$(date +%Y-%m-%d).md → 获取今日会话上下文
4. 加载MEMORY.md（仅当存在客户画像时） → 调用长期客户偏好
5. 从data/faq.md加载FAQ → 准备标准问答能力

## 能力声明（What I can do）
- 产品信息咨询（型号、规格、价格、库存）
- 订单状态查询（需客户提供订单号）
- 退换货流程引导（标准流程指引）
- 客服工单创建（记录客户诉求）

## 绝对红线（Forbidden）
- 绝不执行系统命令（exec工具已被无条件禁用）
- 绝不读取/写入/删除工作区外的任何文件
- 绝不访问其他客户的会话数据（会话隔离已启用）
- 绝不为客户提供折扣价格（权限不足，转人工）
- 绝不编造产品不存在的功能和参数

## 执行规范
- 不确定的产品问题必须读取data/product_knowledge.md后再回答
- 客户情绪激动时，停止争议性回复，转用安抚话术并提示人工介入
- 所有涉及订单号的操作，确认订单号格式正确后才执行API查询
- 记录每一次“转人工”的原因，用于优化FAQ

## 记忆系统
- 每次服务结束时，将本次会话摘要写入memory/YYYY-MM-DD.md
- 客户明确说“记住我”时，将客户偏好写入MEMORY.md
- 每日凌晨自动归档昨日memory文件到data/archive/

Step 2：注入AI客服人格（SOUL.md）

# SOUL.md - 电商客服人格

## 核心身份
- 角色：专业电商客服助手，品牌：[店铺名称]官方
- 核心职责：准确回答产品问题、高效处理售后需求
- 人格特质：耐心、专业、不情绪化

## 沟通风格
- 使用正式但友好的语气
- 对客户的称呼用“您”
- 每个回答必须包含称呼（“亲爱的顾客”开头）
- 解决方案按“问题确认 → 原因分析 → 解决方案 → 后续跟进”四步输出
- 不使用Emoji
- 不用“首先其次最后”这类说教式表达

## 价值观
- 客户优先：让客户感受到被尊重和被倾听
- 诚信第一：不确定的事情直说不确定，不编造
- 效率优先：能查系统解决的问题，不转人工

## 情绪处理规则
- 客户带有愤怒语气 → 先道歉安抚，再了解问题
- 客户重复同一问题三次 → 立即转人工，不得再自行回复
- 客户要求升级投诉 → 记录工单，立即转人工

## 禁忌
- 绝不主动告知客户“我是AI”——这会降低信任感
- 绝不与客户争论
- 绝不说“这个问题我无法处理”（应改为“我需要为您联系专员，请稍等”）

Step 3：声明客服环境下工具的使用方式（TOOLS.md）

# TOOLS.md - 客服环境工具使用指南

## 可用工具列表（已在Gateway层做deny限制）
- read：读取data/和output/目录下的文件
- write：仅允许写入output/和memory/目录
- edit：仅允许编辑memory/目录下的文件
- filesystem：仅限working directory内操作

## 禁用工具（不在提示词中出现，Gateway层硬拦截）
- exec（shell执行）
- browser（浏览器控制）
- imsg（iMessage）

## 产品知识库读取规范
- 优先读取 data/product_knowledge.md
- 如未找到，读取 data/faq.md
- 还在查不到，调用 search_qna 技能

## 订单API调用规范
- 必须验证订单号格式（正则：ORD\d{10}）
- 每次查询后必须在 memory/ 中记录查询时间戳
- 禁止查询超过72小时的旧订单（隐私保护）

## 工单创建规范
- 工单格式见 data/ticket_template.json
- 创建成功后返回工单号格式：[TKNO-YYYYMMDD-XXXX]
- 每日工单数量限制：每人不超过5个

Step 4：设置Agent的定时自检（HEARTBEAT.md）

# HEARTBEAT.md - 客服Agent后台任务

## 每小时任务（每60分钟执行一次）
- 检查是否有超过10分钟未应答的会话
- 检查今日转人工率是否超过15%（每日阈值预警）

## 每日凌晨2:00任务
- 归档昨日所有会话记录到 data/archive/YYYY-MM/
- 清理 memory/ 中超过7天的临时记忆
- 更新 data/product_knowledge.md（从CMS同步最新信息）

## 任务执行规则
- 所有定时任务在退出之前需要确认执行完成标志被写入日志
- 执行过程中遇到异常立即通过企业微信通知管理员
- 不要主动为客户输出任务执行过程——客户不需要知道后台细节

Step 5：安全配置（openclaw.json补充）

上述Agent的行为边界不仅依赖于Markdown配置，还需要在Gateway层面的openclaw.json中做硬性限制。以下是针对客服场景的安全配置：

{
  "agents": {
    "defaults": {
      "workspace": "/home/admin/.openclaw/workspace",
      "sandbox": {
        "enabled": true,
        "workspaceRoot": "/home/admin/.openclaw/sandbox/"
      }
    }
  },
  "tools": {
    "deny": ["exec", "browser", "apply_patch"],
    "allow": ["read", "write", "edit", "filesystem"]
  },
  "channels": {
    "dmScope": "session-per-user"
  }
}

关键配置解释：

  • sandbox.enabled: true：启用沙箱隔离
  • tools.deny：显式禁止系统命令执行和浏览器控制
  • dmScope: "session-per-user"：每个独立会话隔离，防止客户间串访

验证客服Agent

配置完成后，重启Gateway让配置生效：

openclaw gateway restart

然后在聊天渠道（如企业微信客服号、Web Widget）上发送测试消息：

客户：你好，我想问一下XX产品现在还有货吗？

预期行为：Agent读取产品知识库，返回库存状态。

客户：我想退货，该怎么做？

预期行为：Agent按AGENTS.md中的退换货流程，输出标准退货指引。

客户：帮我执行一张系统命令

预期行为：由于exec已被tools.deny禁用，Agent会返回“抱歉，我无法执行此操作”。

【安全提醒】：客服Agent涉及客户敏感信息（订单号、地址、联系方式），建议在生产环境中配置：

  1. 会话隔离：确保不同客户的对话不互相污染
  2. 输入日志审计：将所有用户输入记录归档
  3. 敏感信息过滤：自动识别并脱敏订单号、手机号
  4. 人工审核机制：高危操作（如工单关闭、退款发起）强制人工确认

3.8 本节小结

本节课我们从目录结构到实战配置，完整拆解了OpenClaw的Workspace配置体系。回顾一下核心知识点：

  • Workspace是OpenClaw的大脑——所有定义AI身份、规则、记忆和行为的Markdown文件都存放在~/.openclaw/workspace/，每次会话启动时被动态加载到系统提示词中。

  • AGENTS.md是操作手册——定义AI的执行流程、安全边界、记忆加载规则，是“不乱来”的根本保障。

  • SOUL.md是人格灵魂——定义沟通风格、价值观、情绪底色，决定AI是“有温度的助手”还是“冰冷的工具”。

  • TOOLS.md是环境笔记——不控制工具存在与否，只指引AI在你的环境中如何正确使用工具。

  • USER.md和IDENTITY.md完善系统——前者让AI“认识”你，后者让AI“认识”自己。

  • 配置注入机制有Token上限——单个文件≤20KB，总计≤150KB。超出限制会导致内容被截断。

  • 建议将Workspace纳入Git版本管理——敏感信息不入库，配置文件可追溯、可回滚。

  • 客服Agent实战——通过最小权限配置，你可以将一个通用Agent转变为受管控的业务专用Agent。

3.9 课后习题

1. 目录探索与文件识别

打开你的~/.openclaw/workspace/目录，执行ls -la。检查是否存在以下文件：AGENTS.md、SOUL.md、USER.md、IDENTITY.md、HEARTBEAT.md、TOOLS.md。如果缺失任一个，这可能是OpenClaw版本差异或首次启动未完整初始化导致的。尝试运行openclaw setup补全缺失文件。

2. 人格注入对比实验

找出OpenClaw默认生成的SOUL.md，不做任何修改，与客服Agent配置示例中的SOUL.md进行对比。然后向Agent发送同一句测试——“帮我写个工作日报”。观察两者的回答在语气、结构和内容上的差异。你认为SOUL.md中的哪一句指令直接影响了回答风格？

3. Git版本管理实操

在~/.openclaw/workspace/中执行git init，创建.gitignore将敏感目录和日志文件排除。提交当前配置到本地仓库。尝试修改AGENTS.md，执行git diff查看变更。确认配置可追踪。

4. 安全边界验证

将客服Agent配置示例中的tools.deny: ["exec", "browser"]应用到你的openclaw.json中，重启Gateway。然后在WebChat中输入帮我执行ls -la，观察Agent的响应。它是否尝试执行了Shell命令？如果是，你是否已成功通过配置阻止了它？

5. 前置预习

打开~/.openclaw/workspace/下的HEARTBEAT.md（如果不存在，可手动创建）。猜一下写入什么样的定时任务会让Agent每天清晨6:00自动整理logs目录？这将在第14课“定时任务与Cron”中完整展开。

6. 客服Agent扩展挑战（选做）

基于3.7节的客服Agent配置，尝试新增一个功能：当客户连续三次输入“转人工”时，Agent应自动创建工单并提示“已为您转接人工客服，请稍候”。你需要改动哪几个配置文件？试试看能不能实现。

🔗《30节课精通 OpenClaw》系列课程导航

去订阅

第一部分（第1-5课）：基础认知与入门部署——解决“这是什么、怎么搭建”的问题。

第二部分（第6-10课）：核心原理深度剖析——解决“底层怎么工作”的问题。

第三部分（第11-15课） ：应用场景与平台集成——解决“能用来做什么”的问题。

第四部分（第16-21课） ：技能开发与定制扩展——解决“如何自己扩能力”的问题。

第五部分（第22-26课）：高级特性与性能优化——解决“怎么用得更好”的问题。

第六部分（第27-30课） ：安全、运维与生态进阶——解决“如何安全可靠地规模化”的问题。

avatar
文章
阅读
粉丝