# Claw Agent Workspace

> 动态管理 Claw 系列智能体（含 OpenClaw 及同级别 Claw Agent 实现）的工作区引导文件。自动扫描关联技能目录，提取关键词和模块路由，生成动态"核心技能触发块"注入 AGENTS.md，按需写入脚本铁律和技能感知叠加层。当用户提到"claw""智能体配置""引导文件""工作区文件""AGENTS.md""SOUL.md"或"升级 agent""配置 agent"时使用。

- Skill: `legalskill/claw-agent-workspace` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add legalskill/claw-agent-workspace`
- Raw SKILL.md: https://api.skillmd.com/api/skills/legalskill/claw-agent-workspace/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: CC BY-SA 4.0
- Author: legalskill (https://skillmd.com/u/legalskill)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/legalskill/claw-agent-workspace

---


# Claw 工作区管理

本技能动态管理 Claw 系列智能体（含 OpenClaw 及同级别 Claw Agent 实现）的工作区引导文件和配置。核心能力：扫描绑定技能目录 → 提取关键词和模块路由 → 生成动态"核心技能触发块"注入 AGENTS.md——任何 agent 通过升级即可自动获得"关键词检测→强读技能文件→模块路由"机制，且与当前技能动态适配。

## 概述

Claw 是一个嵌入式智能体运行时，每个网关对应一个智能体进程。配置文件（`配置.json`，JSON5 格式，支持注释和尾随逗号）位于用户配置目录下，工作区引导文件为智能体提供人设、指令和记忆。

本技能将指导你：
1. 创建和修改主配置文件
2. 创建和修改工作区引导文件（AGENTS.md、SOUL.md 等）
3. 使用内置默认模板快速启动

## 本技能的运行约束

### 规则1：模板使用
- 新建工作区引导文件时，必须使用 `assets/` 下的默认模板作为起点。
- 模板路径从本技能根目录推导：`<本技能目录>/assets/<模板名>`。
- 不可直接复制模板全文到对话中，应使用"读取模板 + 根据用户需求改写 + 写入目标路径"的工作流。

### 规则2：文件路径与引用
- 配置文件路径以用户配置目录为根。
- 工作区文件位于配置中指定的工作区目录。
- 阅读参考文档时，使用条件触发格式："如果需要配置 <功能>，读取 `references/<文件>`"。

### 规则3：含脚本技能的引导文件约束（重要）

当目标工作区管理的技能包含 `scripts/` 目录时，AGENTS.md 必须写入以下 5 条基础铁律（通过 `{{SCRIPT_RULES}}` 占位符注入）。此外，第 0 步扫描时检测到的技能特有限制，编码和凭证约束写入 `{{SKILL_RED_LINES}}`，额外内部操作写入 `{{SKILL_SAFE_ACTIONS}}`：
- 技能文件提到编码要求 → 追加写入前编码校验规则
- 技能有凭证脚本 → 追加凭证安全规则
- 技能文件中有其他硬约束 → 提取关键语义追加

基础铁律：

1. **必须使用预置脚本，禁止内联代码**：所有功能通过技能 `scripts/` 目录中的预置脚本执行。严禁自行编写替代脚本或用内联代码实现相同功能。
2. **脚本路径必须从技能文件绝对路径推导**：`<技能目录>/scripts/<脚本名>`。
3. **依赖缺失时先安装再运行**：如 `pip install requests` 等。
4. **预置脚本缺陷修复原则**：证实存在 BUG 时允许最小化修复——仅针对 BUG 本身，不得改变接口/行为/功能范围；修复后必须说明改了哪个脚本、什么内容、为什么；若 BUG 无法最小修复或涉及设计变更，停止自行修改并向用户说明。
5. **新增功能的处理流程**：确认现有脚本无法实现 → 向用户说明需新增功能点 → 获得明确许可后方可添加；未获许可前严禁擅自新增。

## 修改模式

操作的文件（配置文件、引导文件等）**直接注入大模型系统提示或控制网关行为**，写错即影响智能体运行。因此修改前必须判定模式，对应不同的安全策略。

### 标准模式（L1，默认）
- **触发条件**：单个字段修改、数值调整、添加白名单条目、一句话补充——改动范围小，不影响整体结构。
- **行为**：
  1. 直接定位到目标字段/段落，精准修改。
  2. 修改后提示验证命令。
- **风险**：极低。

### 深度模式（L2）
- **触发条件**：
  1. 用户消息含"大改/重构/重写/全新/替换/重新设计/翻新"等关键词；
  2. 用户要求同时改动多个引导文件（如同时改 SOUL.md + AGENTS.md）；
  3. 改动范围超过文件内容的 30%；
  4. 重写配置文件的整个顶层模块（如重建智能体默认配置块）。
- **行为**：
  1. **备份先行**：修改前先在目标文件同级目录创建带时间戳的备份（`文件名.bak-年月日-时分`）。
  2. 根据用户需求完整重写目标内容。
  3. 修改完成后，输出变更摘要——列出删除/新增/修改的关键内容。
  4. 验证后询问用户是否删除备份文件；无回复则保留。
- **回滚**：将备份文件覆盖回目标文件。
- **风险**：中高。配置文件改写错误可能被热重载瞬间激活。

### 模式判定速查

| 用户输入 | 改动范围 | 模式 |
|:---------|:---------|:------|
| 无深度关键词 | 单字段/单段落 | 标准（自动） |
| 无深度关键词 | 跨文件或多模块 | 暂停确认 → 同意则深度 |
| 含"大改/重写/替换"等关键词 | 任意 | 深度（自动） |

## 核心工作流

本技能在每次操作中遵循以下流程。**动态感知先行，最后一步为强制审查，不可跳过。**

### 0. 动态扫描（前置）

在执行任何操作前，先扫描目标工作区关联的技能。根据用户指定范围确定要处理的文件。

决策逻辑：

```
收到任务
  │
  ├─ 用户指定了具体文件？
  │     └─ 是 → 仅处理指定文件
  │
  ├─ 用户提到了具体技能名/路径？
  │     └─ 是 → 扫描该技能目录
  │
  ├─ 用户提到了某个工作区？
  │     └─ 是 → 读取该工作区的 AGENTS.md，提取技能绑定信息
  │
  └─ 都没有？→ 向用户确认目标工作区和技能范围
```

扫描后判定是否进入单技能融合策略。满足以下任一条件即触发：

1. 用户明确提到"单技能"
2. 用户指定了具体的技能目录（如"用 `D:\legalskill\claw-agent-workspace\` 这个技能"），意图明确指向单一技能
3. 扫描发现工作区/专家仅有 1 个绑定技能

触发单技能后，进入**现存绑定检测**（兜底，不可跳过）：

- 目标工作区无 AGENTS.md → 新建，直接走精简管道
- 有 AGENTS.md → 读取并检测现有绑定状态：
  - 已用 CORE_SKILL_BLOCK（多技能格式）？
  - 已用 Tools & Skills 表格注册？
  - 已有技能数量（N_old）vs 用户新指定/扫描到的技能（N_new）？
  - **存在冲突** → 暂停，列出冲突详情，请求用户确认后再继续

冲突清单（任一命中即暂停）：
- N_old >= 2 但用户要求单技能 → 降级冲突（丢失多技能路由）
- N_old == 1 但技能路径/名称与用户指定不一致 → 覆盖冲突（旧技能被替换）
- 已有表格注册 vs 用户指定外部路径 → 注册格式冲突（相对 vs 绝对路径）
- 用户指定技能目录不在现有绑定中 → 新增冲突（可能变为多技能）

检测通过（无冲突或用户已确认）→ 进入单技能融合策略，详见[单技能融合策略](#单技能融合策略)章节。未触发（多技能或未指定）→ 使用完整管道。

扫描技能目录时采集以下信息：

| 检测项 | 执行动作 |
|:-------|:---------|
| 技能目录存在 | 读取技能主文件（`SKILL.md` 或入口 Markdown 文件） |
| 技能文件中存在"关键词""触发"等标记 | 提取触发关键词列表和模块路由规则 |
| 未找到显式关键词列表 | 自动生成候选后暂停，列出候选交由用户确认 |
| 技能含 `scripts/` 且目录非空 | AGENTS.md 必须写入脚本使用铁律 |
| 技能含配置文件（如 `config.py`） | AGENTS.md 中声明"执行前读取配置获取运行时参数" |
| 技能文件中提到编码要求 | 记录到技能特有规则 |
| 技能文件中提到凭证/密钥管理要求 | 记录到技能特有规则 |
| 用户消息含"配合""协同""同时运行"等词 | 检测为多技能工作区，需构建路由表 |
| 用户消息含"升级""大改"等词 | 判定为 L2 深度模式 |

**关键词提取子步骤（扫描到任一技能后自动执行）：**

1. 从技能文件提取：技能名称（优先级：前置元数据 name > 第一个标题 > 目录名）、主要触发关键词列表、子模块信息、特殊约束。
2. 若关键词缺失采用自动生成规则：
   - 从技能名称中拆词——中文名直接按语义拆分；英文名按连字符/驼峰边界拆分（如 `claw-agent-workspace` → claw、agent、workspace），中文描述中取对应概念；
   - 对每个核心词扩展 2-4 个中文同义/近义/口语化表达；
   - 若技能文件描述了具体功能，生成对应功能的自然语言问法（如"工作区配置" → "帮我配置工作区""升级一下 agent"）；
   - **暂停操作，列出生成的关键词，请求用户确认或调整**。
3. 构建关键词路由表（格式见模板 `assets/CORE_SKILL_BLOCK.md`），若多技能则构建跨技能路由表。

**核心原则：根据实际扫描结果动态决定写入哪些规则，不写一刀切的模板。**

### 1. 确定需求
- 明确操作类型：首次搭建、增量修改（L1）、还是深度重构（L2）？
- 确认影响范围：只改配置文件的某个字段？还是连带修改引导文件？
- 基于第 0 步扫描结果，判断是否涉及技能配合、是否含脚本。

### 2. 判定模式
- 按[修改模式](#修改模式)速查表判定 L1（标准）或 L2（深度）。
- L2 时先告知用户将执行备份，确认后再动手。
- 用户消息模糊不清时，暂停并询问确认——配置写错不可逆。

### 3. 执行修改
- **配置文件**：按字段路径精准定位 → L2 先备份 → 输出配置块 → 提示验证命令。
- **引导文件**：新建用模板改写、修改用 L1/L2 分支流程。详见下方[工作流](#工作流-1)的各步骤。
- **含脚本的技能**：第 0 步检测到 `scripts/` 目录的，AGENTS.md 中必须写入规则3的 5 条脚本铁律。
- **核心技能触发块注入**（强制）：第 0 步扫描到任一技能时，必须读取 `assets/CORE_SKILL_BLOCK.md`，用扫描得到的关键词、模块路由填充占位符，生成动态触发块注入到 AGENTS.md 中。新建时插入到合适位置，修改已有文件时 L1 精准替换、L2 完整重写时包含。多技能时在 TOOLS.md 中写入跨技能路由表（技能名 | 触发关键词 | 入口文件）。
  - **豁免**：进入单技能融合策略时，跳过 CORE_SKILL_BLOCK 注入，改用 `assets/AGENTS.md` 的 `{{SKILL_TABLE}}` 表格注册。

### 4. 结构验证
- 配置文件：使用诊断命令验证。
- 引导文件：检查语法（Markdown 是否合法）、估算字符数（是否超过单文件注入上限）。

### 5. 配置审查（强制）

完成修改后，逐项确认以下 8 条原则。**任一不满足则必须回退修正**。

| # | 原则 | 检查点 |
|:--|:-----|:-------|
| 1 | **最小化** | 是否只写了必需字段？有没有画蛇添足的默认值等价物？引导文件有没有教科书式的废话？ |
| 2 | **安全性** | 密钥有没有硬编码？是否使用了环境变量引用？ |
| 3 | **一致性** | SOUL.md 的"专业纪律"是否与 AGENTS.md 的核心技能触发规则一致？SOUL.md 的"技能边界"是否覆盖了技能文件中声明的所有约束？SOUL.md 的语气与 AGENTS.md 的流程要求是否自洽？配置文件中引用的发送者是否与 USER.md 匹配？ |
| 4 | **精简** | 引导文件单文件是否 < 12000 字符？总计是否 < 60000 字符？配置文件有没有冗余注释或废弃块？ |
| 5 | **可回滚** | L2 操作是否已创建时间戳备份？用户知不知道回滚路径？ |
| 6 | **副作用意识** | 改动网关配置字段时是否提醒了需要重启？修改 SOUL.md 时是否说明了这会影响所有后续对话的语气？ |
| 7 | **智能体记忆保护** | 以下文件默认受保护，L2 重写不得覆盖已填写内容：IDENTITY.md、USER.md、MEMORY.md。AGENTS.md 和 SOUL.md 中用户自定义部分（非模板内容）须提取并合并。 |
| 8 | **不重复技能内容** | 工作区文件有没有写入版本号、数据源网址、命令参数、采集方式等技能自有信息？技能升级后这些会过期成灾难。工作区文件只存路径引用，细节永远是读技能文件获得。 |

审查通过后，给出总结："本次修改为 [L1/L2] 模式，影响范围 [X]，已备份 [是/否]，已通过验证 [是/否]"。

## 工作流

### 1. 初始化配置（首次使用）

全新工作区属于深度模式操作。步骤：

1. **创建最小化配置**：生成配置文件，至少包含工作区路径和访问控制。
2. **创建工作区引导文件**：根据用户需求使用 `assets/` 下的模板创建必要的引导文件。
3. **验证配置**：提示用户运行诊断命令检查配置有效性。

**最小化配置模板：**
```json5
// 配置文件（JSON5 格式）
{
  agents: { defaults: { workspace: "工作区路径" } },
  // 根据用户选择的频道填写允许列表
}
```

### 2. 修改配置文件

1. **判定模式**：根据改动范围和用户措辞判定 L1 / L2（见上方修改模式）。
2. **L2 先备份**：深度模式先执行备份。
3. **定位并修改**：确认目标路径（如 `智能体.默认.模型`），输出配置块。
4. **验证**：修改后运行诊断命令。

**快捷修改方式（适合 L1）：**
```bash
claw config get 智能体.默认.工作区
claw config set 智能体.默认.心跳.间隔 "2h"
claw config set 智能体.默认.模型 '<json>' --strict-json --merge
```

### 3. 创建/修改工作区引导文件

这些文件**每次会话都注入大模型上下文**。改错一行，智能体行为立刻偏离。

**如果目标工作区绑定了技能，且用户意图为"升级 agent"或"新建带技能的工作区"，必须在 AGENTS.md 中注入核心技能触发机制。**

#### 核心技能块注入流程

1. **已获取扫描信息** → 从第 0 步获取所有技能的触发关键词、模块结构、特殊约束等。
2. **读取模板** → 读取 `assets/CORE_SKILL_BLOCK.md`。
3. **填充 CORE_SKILL_BLOCK 占位符**：用主要技能的信息填充。CORE_SKILL_BLOCK 始终只保留当前主要技能的关键词表。若多技能，跨技能路由表仅在 TOOLS.md 中生成（见下文）。
4. **填充 AGENTS.md 技能占位符**：用第 0 步扫描结果替换三个占位符，替换内容必须保持列表格式（每行以 `- ` 开头，与模板已有条目一致）：
   - `{{SKILL_RED_LINES}}` — 技能边界、编码强制、凭证安全等约束；
   - `{{SCRIPT_RULES}}` — 检测到 `scripts/` 时替换为 5 条脚本铁律（独立 `##` 章节），无脚本时替换为空字符串（删除该行）；
   - `{{SKILL_SAFE_ACTIONS}}` — 技能允许的额外内部操作，无内容时替换为空字符串（删除该行）。
5. **集成到 AGENTS.md**：
   - 新建 AGENTS.md：将填充后的块插入到 `<!-- CORE_SKILL_BLOCK 在此处动态注入 -->` 所在位置（替换该注释行）。
   - 修改已有 AGENTS.md：已有核心技能块则 L1 精准替换；没有则插入。
   - L2 深度重写：重写后的文件直接包含该块。
6. **不写入版本号、数据源网址、API 端点**——生成的块只含路径引用和一般性规则。

#### SOUL.md 两层架构处理规则

SOUL.md 采用"通用人格基座 + 技能感知叠加层"双层架构：

**单技能场景（进入单技能融合策略时）：**
- 不启用双层架构。直接从技能 SKILL.md 提取人格描述（身份、个性、语气、边界），融合写入 SOUL.md。
- 不读取 `SOUL_SKILL_LAYER.md`，不追加叠加层。
- 修改已有工作区时，若 SOUL.md 当前是双层架构但变为单技能 → L1 移除叠加层，将技能人格融入基座。

**多技能场景：**

**新建工作区：**
1. 先写入 `assets/SOUL.md`（通用人格基座——纯人格，不含技能内容）。
2. 如果工作区绑定了技能：
   - 读取 `assets/SOUL_SKILL_LAYER.md`。
   - 填充占位符：从技能文件提取专业领域描述和边界约束，逐条列出。
   - 追加到 SOUL.md 末尾（通用基座在上，技能感知层在下）。

**修改已有工作区：**
- SOUL.md 不含技能感知层、但工作区已绑定技能 → L1 追加技能感知层。
- SOUL.md 已有技能感知层、但技能已变更 → L1 替换技能感知层。
- 用户自定义了 SOUL.md 大部分内容 → **保护用户内容**，仅精准更新技能感知层。
- L2 深度重写 → 完整重写，通用基座 + 技能感知层全部重新生成。

#### 文件清单与注入时机

| 文件 | 注入时机 | 注意事项 |
|:-----|:---------|:---------|
| BOOTSTRAP.md | 全新工作区首次会话 | 完成引导后**必须删除** |
| AGENTS.md | 每次会话 | 操作规则和记忆习惯。**含技能时必须包含核心技能触发块** |
| SOUL.md | 每次会话 | 人设、语气、边界。采用双层架构 |
| USER.md | 每次会话 | 用户档案 |
| IDENTITY.md | 每次会话 | 名称/emoji/头像 |
| TOOLS.md | 每次会话 | 本地工具约定。多技能时承载跨技能路由表 |
| HEARTBEAT.md | 心跳会话 | 保持简短避免 token 浪费 |
| BOOT.md | 网关重启时 | 需启用内部 hooks |

#### 创建流程（全新文件）

1. 读取 `assets/<文件名>` 获取默认模板。
2. 根据用户具体偏好改写。
3. 若为 AGENTS.md 且绑定了技能，执行核心技能块注入流程。
4. **若为 BOOTSTRAP.md 且全新工作区**：
   - 检查 IDENTITY.md 状态：若已填写完整（姓名、emoji、头像、气质均有值）→ 生成模式 B（身份既定式）：跳过身份协商，直接以技能身份打招呼，引导流程简化为确认 USER.md 后删除。
   - 若 IDENTITY.md 为空或不存在 → 生成模式 A（系统默认探索式引导），并在"搞清楚你是谁之后"段落后插入一句技能告知（如"阅读 AGENTS.md 了解我的核心能力"）。若工作区绑定了技能，模式 A 下也在此处追加提醒。
5. 写入工作区对应路径。

#### 修改流程（已有文件）

1. **L1**：读取当前文件 → 定位目标段落 → 精准修改 → 保存。若涉及技能信息更新，L1 精准替换核心技能触发块。
2. **L2**：
   1. **记忆提取**：读取当前文件，标记以下受保护内容：
      - 用户明确写入的偏好（如"用户说过"开头的内容、对话中用户要求记住的信息）；
      - MEMORY.md 中引用过的段落；
      - 与 `assets/` 模板对比后，用户自行添加的非模板内容。
   2. 创建时间戳备份。
   3. 完整重写（含重新生成的核心技能触发块和技能感知层），并将受保护内容合并进去。
   4. 输出变更摘要，**显式列出保留的记忆条目**。

> 大文件会被截断注入（默认单文件 12000 字符，总计 60000 字符），因此引导文件必须保持精简。

如果需要自定义人设风格，读取 `references/soul-guide.md` 获取 SOUL.md 编写指南。

如果需要了解完整配置字段的精确语义和默认值，读取 `references/config-reference.md`。

## 单技能融合策略

当工作区/专家仅绑定一个技能时（触发条件见 Step 0 决策树），走精简管道而非完整的多技能管道。核心区别如下：

### SOUL 融合模式

跳过"通用人格基座 + 技能感知叠加层"双层架构。直接从技能的 `SKILL.md` 中提取身份、个性、语气、边界等描述，融合写入单一 `SOUL.md`。不读取 `assets/SOUL_SKILL_LAYER.md`，不追加叠加层。

**示例**：技能 `claw-agent-workspace` 的 SKILL.md 中描述了"动态管理 Claw 系列智能体的工作区引导文件"——单技能 agent 的 SOUL.md 直接以此为"我是谁"。

### AGENTS.md 表格注册

不使用 CORE_SKILL_BLOCK（关键词路由表对单技能无意义）。改用 `assets/AGENTS.md` 模板中 `{{SKILL_TABLE}}` 占位符填充简单表格，配合毯式必读规则：

**技能在工作区内**（如 `skills/claw-agent-workspace/SKILL.md`）：

```
| Skill | Purpose |
|-------|---------|
| `skills/claw-agent-workspace/SKILL.md` | 动态管理 Claw 智能体工作区引导文件... |
```

**技能在外部路径**（如 `D:\legalskill\claw-agent-workspace\SKILL.md`）：

```
| Skill | Purpose |
|-------|---------|
| `D:\legalskill\claw-agent-workspace\SKILL.md` | 动态管理 Claw 智能体工作区引导文件... |
```

配合毯式规则：`MANDATORY: Before starting ANY task, read and follow all SKILL.md files listed above.`

### 跳过 CORE_SKILL_BLOCK

单技能时不需要关键词路由表，不注入 `CORE_SKILL_BLOCK`。`assets/CORE_SKILL_BLOCK.md` 模板保留（多技能仍需使用），但单技能管道不调用。

### 外部路径技能处理

当技能不在工作区 `skills/` 子目录下，而是外部独立路径时：

- AGENTS.md 中技能路径写**绝对路径**
- 若外部技能含 `scripts/`：路径推导从外部技能目录推导。AGENTS.md 中写入脚本铁律时，路径格式为 `<外部技能绝对路径>/scripts/<脚本名>`
- 若外部技能含 `config.py`：声明"执行前读取外部技能目录下的配置获取运行时参数"
- 其他约束（脚本铁律、安全红线等）与工作区内技能完全一致

### 与多技能管道的切换

- 单技能 → 多技能：当工作区新增第二个技能时，自动升级为完整管道（CORE_SKILL_BLOCK + 双层 SOUL + TOOLS.md 跨技能路由表）
- 多技能 → 单技能：需用户明确确认降级（因会丢失现有多技能路由表）。触发"降级冲突"，暂停请求确认。

## 可用模板

本技能在 `assets/` 目录下提供以下默认模板，创建新文件时使用：

| 模板文件 | 用途 | 使用时机 |
|:---------|:-----|:---------|
| `assets/AGENTS.md` | 操作指令和记忆规则（含会话启动、记忆、红线、内外操作固定结构；占位符：`{{SKILL_RED_LINES}}`/`{{SCRIPT_RULES}}`/`{{SKILL_SAFE_ACTIONS}}` 用于动态注入技能约束与脚本铁律；`<!-- CORE_SKILL_BLOCK ... -->` 为触发块注入锚点） | 创建/更新 AGENTS.md |
| `assets/CORE_SKILL_BLOCK.md` | 核心技能触发块（仅触发和路由逻辑，不含技能特有约束） | 升级/新建带技能的 agent 时自动填充注入 |
| `assets/SOUL.md` | **通用人格基座**——所有 agent 的出厂人设，不含技能内容 | 新建 SOUL.md 时作为底层 |
| `assets/SOUL_SKILL_LAYER.md` | 技能感知叠加层 | 绑定技能时动态填充，追加到 SOUL.md 末尾 |
| `assets/TOOLS.md` | 本地工具约定（多技能时承载跨技能路由表） | 创建 TOOLS.md；多技能工作区升级时更新 |
| `assets/BOOTSTRAP.md` | 首次运行引导（根据 IDENTITY.md 状态自动选择探索式或身份既定式，绑定技能时插入技能告知段） | 全新工作区创建 |
| `assets/USER.md` | 用户档案模板 | 创建 USER.md |
| `assets/IDENTITY.md` | 智能体身份记录 | 首次引导时创建 |
| `assets/HEARTBEAT.md` | 心跳检查清单 | 创建 HEARTBEAT.md |
| `assets/MEMORY.md` | 长期记忆容器模板（中文，含加载规则摘要） | 创建 MEMORY.md |

使用模板时：
1. 读取 `assets/<模板名>` 获取默认内容
2. 根据用户的具体偏好改写
3. 写入工作区对应文件路径

## 备份与临时文件

`scratch/` 目录存放开发过程中的临时产物（`.bak` 备份、测试数据等），与技能运行无关。Agent 不会自动执行该目录下的任何文件。

每次 L2 深度模式操作会生成 `.bak-YYYYMMDD-HHMM` 备份文件。长期积累会占用空间并对 LLM 上下文造成干扰（备份文件可能被误读）。

**清理规则：**
- 每次升级完成后，主动提示用户"是否清理旧备份"，列出当前所有备份文件及时间。
- 默认保留最近 3 次备份，更早的删除。
- 用户明确要求"清理备份"时，删除目标工作区内所有 `.bak-*` 文件。
- 若工作区使用 git 管理，无需保留 `.bak-*` 文件——git 历史本身就是备份。

## 配置热重载

Claw 支持配置热重载，无需手动重启。重载模式控制行为：

| 模式 | 行为 |
|:-----|:-----|
| 混合（默认） | 安全变更即时生效，关键变更自动重启 |
| 热 | 仅热应用安全变更 |
| 重启 | 任何变更都重启 |
| 关闭 | 禁用文件监听 |

大部分字段支持热应用，仅网关服务器配置（端口、绑定等）和服务发现、插件需要重启。

## 可用脚本

本技能自身不包含可执行脚本。但目标工作区管理的技能可能含 `scripts/` 目录——此时**规则3（含脚本技能的引导文件约束）必须写入对应 AGENTS.md**。

## 关键约束 (重要提醒)

- **这些文件直接影响大模型行为**：引导文件的内容在每个会话开始时被注入系统提示。改错一行，智能体的语气、边界、操作规则立刻偏离。这跟修改技能文件本身是同一级别的影响。因此 L2 深度模式必须备份。
- **配置文件严格验证**：未知键、错误类型或无效值将导致网关**拒绝启动**。网关在每次成功启动后保留一份内部备份，诊断命令可恢复。
- **配置格式必须为 JSON5**：支持注释和尾随逗号。敏感字段中不要写注释。
- **工作区是智能体的唯一工作目录**：工具的相对路径解析基于工作区。
- **引导文件缺失时注入"缺失文件"标记**：如果 SOUL.md 等文件不存在，Claw 会在系统提示中注入缺失标记，提示智能体该文件缺失。
- **大文件会被截断注入**：默认单文件 12000 字符，总计 60000 字符。超出部分被截断并附截断标记。引导文件必须保持精简。
- **引导文件是记忆载体，不是配置**：AGENTS.md 和 MEMORY.md 会随使用积累经验——修改时务必保留用户已经积累的有效规则和上下文，不要用模板直接覆盖。默认受保护文件：IDENTITY.md、USER.md、MEMORY.md。
- **工作区文件不应存储秘密信息**：即使在私有仓库中，也不要在工作区存储密钥、令牌等凭据。
- **含脚本技能的引导文件必须写入规则3**：如果目标工作区管理的技能有 `scripts/` 目录，AGENTS.md 中必须包含 5 条脚本铁律。
- **工作区文件不重复技能内容**：版本号、数据源网址、API 端点、命令参数、采集方式——这些是技能自有信息。工作区文件只存路径引用。技能升级后工作区文件里硬编码的旧版本号会变成错误信息。
- **核心技能触发块必须每次从技能目录重新扫描生成**：升级 agent 时，禁止从旧的 AGENTS.md 直接复制粘贴核心技能块。技能的关键词、模块结构可能已变更，必须重新读取技能文件获取最新信息。
- **备份文件会积累**：每次 L2 操作产生 `.bak-YYYYMMDD-HHMM` 文件，长期不清理会挤占空间并可能被 LLM 误读。每次升级完成后主动提示清理，保留最近 3 次即可。git 管理的工作区不需要 `.bak` 文件。

## 验证与诊断

配置完成后使用以下命令验证：

```bash
claw doctor           # 诊断配置问题
claw doctor --fix     # 自动修复已知问题
claw config validate  # 验证配置有效性
claw config schema    # 打印配置规范
```

## 获取帮助

- 如果需要理解特定配置字段的精确语义，读取 `references/config-reference.md`。
- 如果需要编写智能体人设，读取 `references/soul-guide.md`。

> **免责声明**：以上内容由 AI 辅助生成，仅供参考，具体实施前请结合实际情况进行专业判断。严禁将涉密信息输入公域大模型。

*技能版本：1.1.0 | 作者：[律锥·legalskill](https://www.legalskill.cn) | 文档许可：CC BY-SA 4.0*