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 绝对路径）
• 用户指定技能目录不在现有绑定中 → 新增冲突（可能变为多技能）

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

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

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

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 分支流程。详见下方工作流的各步骤。
• 含脚本的技能：第 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 条原则。任一不满足则必须回退修正。

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

工作流

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

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

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

最小化配置模板：

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

2. 修改配置文件

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

快捷修改方式（适合 L1）：

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 深度重写 → 完整重写，通用基座 + 技能感知层全部重新生成。

文件清单与注入时机

创建流程（全新文件）

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/ 目录下提供以下默认模板，创建新文件时使用：

使用模板时：

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 文件。

验证与诊断

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

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

获取帮助

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

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

技能版本：1.1.0 | 作者：律锥·legalskill | 文档许可：CC BY-SA 4.0