Claw Knowledge Base Skill

⚠️ 仅支持 OpenClaw 平台。 其他平台（本地 IDE、CLI、其他 agent 框架）不支持本 skill。

功能： 在 OpenClaw 中为多个 Agent 提供共享知识库。顶层目录下的 .md 文件会被索引，Agent 可通过 memory_search 检索，并按分类目录写入知识。

两类核心操作：

• 读取：用 memory_search 做语义检索，或按 kb:// 路径直接读取文件
• 写入：把 Markdown 内容写入 KNOWLEDGE_BASE_DIR 下的合适分类目录

⚡ 操作速查

🚀 Quick Start

1. 设置知识库目录（选择一种方式）

   方式 A — 配置文件（推荐）：创建 $WORKSPACE/.config/claw-knowledge-base.json（或 ~/.config/claw-knowledge-base.json）：

   { "KNOWLEDGE_BASE_DIR": "/path/to/your/knowledge-base" }

   方式 B — 环境变量：

   export KNOWLEDGE_BASE_DIR="/path/to/your/knowledge-base"

   也可在 openclaw.json 的 env 字段中设置：

   { "env": { "KNOWLEDGE_BASE_DIR": "/path/to/your/knowledge-base" } }

2. 检查环境并初始化目录

   python3 scripts/check_env.py
   python3 scripts/init_dirs.py

3. 在 openclaw.json 中加入索引路径

   {
     "agents": {
       "defaults": {
         "memorySearch": {
           "extraPaths": ["${KNOWLEDGE_BASE_DIR}"]
         }
       }
     },
     "env": {
       "KNOWLEDGE_BASE_DIR": "/path/to/your/knowledge-base"
     }
   }

4. 读取与写入

   memory_search "gerrit SSH connection refused"
   cat "$KNOWLEDGE_BASE_DIR/temp/review-result.md"

   python3 - <<'PY'
   import os
   from pathlib import Path
   target = Path(os.environ['KNOWLEDGE_BASE_DIR']) / 'temp' / 'my-result.md'
   target.parent.mkdir(parents=True, exist_ok=True)
   target.write_text('# My Result\n\n内容...', encoding='utf-8')
   print(target)
   PY

路径约定: 以下所有 scripts/... 路径均相对于本 Skill 目录（.agents/skills/claw-knowledge-base/）。

🔗 kb:// 路径参考

kb://<path> 会解析为 $KNOWLEDGE_BASE_DIR/<path>。

📖 完整目录结构说明和最佳实践见 references/directory-guide.md
📖 kb:// 路径用法、memory_search 检索技巧、多 Agent 协作模式见 references/search-patterns.md

📚 参考文件

🔄 常见 Agent 工作流

工作流 1 — Code Review Agent 存档报告

输入：code review 完成后的报告文本

Step 1: 确认 KNOWLEDGE_BASE_DIR 已设置
Step 2: 写入存档目录
  目标路径: kb://code-review/YYYY-MM-DD_<change_number>.md
  内容格式: Markdown，包含变更详情、审查结果、问题列表

Step 3: （可选）同时写临时文件供其他 Agent 消费
  目标路径: kb://temp/review-<change_number>.md
  文件头需包含: expires: YYYY-MM-DD

示例（Python）：

from pathlib import Path
from datetime import date
import os

kb = Path(os.environ['KNOWLEDGE_BASE_DIR'])
change = "12345"
report_path = kb / 'code-review' / f'{date.today().isoformat()}_{change}.md'
report_path.write_text(report_content, encoding='utf-8')

工作流 2 — 检索历史问题解决方案

场景：遇到 Gerrit SSH 连接超时问题，先检索知识库

Step 1: memory_search "gerrit SSH timeout connection refused"
Step 2: 如有结果，读取对应文件
  cat "$KNOWLEDGE_BASE_DIR/troubleshooting/gerrit-ssh.md"
  或通过 kb://troubleshooting/gerrit-ssh.md 引用
Step 3: 按照文件中的解决方案操作
Step 4: 如发现新解法，追加到同一文件（先读后写）

工作流 3 — 多 Agent 传递临时数据

Agent A 写入:
  kb://temp/analysis-<task_id>.md   ← 包含 expires 字段

Agent B 读取和清理:
  1. memory_search "temp analysis <task_id>"
  2. 读取文件内容处理业务逻辑
  3. 删除临时文件（temp/ 目录不保留持久文件）

工作流 4 — 初始化新知识库

# Step 1: 设置路径（config 文件或环境变量）
# Step 2: 检查环境
python3 scripts/check_env.py

# Step 3: 创建标准目录结构
python3 scripts/init_dirs.py

# Step 4: 在 openclaw.json 中注册索引路径（见 Quick Start Step 3）

不支持的场景

明确禁止的操作

• ⛔ 禁止写入密码、API token、内网 IP、私钥等敏感信息：知识库对所有 Agent 可见
• ⛔ 禁止修改其他 Agent 的私有目录（{agent_def_dir}/）：每个 Agent 只写自己的目录
• ⛔ 禁止删除 architecture/、coding-standards/ 等标准目录
• ⛔ 禁止在 KNOWLEDGE_BASE_DIR 根目录直接写入文件（必须进入子目录）
• ⛔ 禁止使用非 Markdown 格式（.txt、.json、.yaml 等）写入知识：这些文件不会被索引
• ⛔ 禁止在文件名中使用空格、大写字母、下划线或中文

边界条件

幂等性声明

🔧 Troubleshooting

快速诊断命令

# 检查环境
python3 scripts/check_env.py

# 确认目录可读写
ls -la "$KNOWLEDGE_BASE_DIR"

# 查看已有文件
find "$KNOWLEDGE_BASE_DIR" -name "*.md" | head -20

# 验证 openclaw.json 配置
cat openclaw.json | python3 -m json.tool | grep -A3 '"extraPaths"'

📋 文件命名规范

📦 依赖说明