249 lines
5.5 KiB
Markdown
249 lines
5.5 KiB
Markdown
# OpenClaw Integration
|
||
|
||
将 self-improvement skill 集成到 OpenClaw 的完整 setup 与使用指南。
|
||
|
||
## Overview
|
||
|
||
OpenClaw 使用基于 workspace 的 prompt injection，并结合 event-driven hooks。上下文会在 session 启动时从 workspace files 注入，hooks 则会在生命周期事件上触发。
|
||
|
||
## Workspace Structure
|
||
|
||
```
|
||
~/.openclaw/
|
||
├── workspace/ # 工作目录
|
||
│ ├── AGENTS.md # 多代理协作模式
|
||
│ ├── SOUL.md # 行为指导与个性
|
||
│ ├── TOOLS.md # 工具能力与 gotchas
|
||
│ ├── MEMORY.md # 长期 memory（仅主 session）
|
||
│ └── memory/ # 每日 memory 文件
|
||
│ └── YYYY-MM-DD.md
|
||
├── skills/ # 已安装 skills
|
||
│ └── <skill-name>/
|
||
│ └── SKILL.md
|
||
└── hooks/ # 自定义 hooks
|
||
└── <hook-name>/
|
||
├── HOOK.md
|
||
└── handler.ts
|
||
```
|
||
|
||
## Quick Setup
|
||
|
||
### 1. Install the Skill
|
||
|
||
```bash
|
||
clawdhub install self-improving-agent
|
||
```
|
||
|
||
或手动复制：
|
||
|
||
```bash
|
||
cp -r self-improving-agent ~/.openclaw/skills/
|
||
```
|
||
|
||
### 2. Install the Hook（可选）
|
||
|
||
将 hook 复制到 OpenClaw 的 hooks 目录：
|
||
|
||
```bash
|
||
cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement
|
||
```
|
||
|
||
启用 hook：
|
||
|
||
```bash
|
||
openclaw hooks enable self-improvement
|
||
```
|
||
|
||
### 3. Create Learning Files
|
||
|
||
在 workspace 中创建 `.learnings/` 目录：
|
||
|
||
```bash
|
||
mkdir -p ~/.openclaw/workspace/.learnings
|
||
```
|
||
|
||
或者在 skill 目录中创建：
|
||
|
||
```bash
|
||
mkdir -p ~/.openclaw/skills/self-improving-agent/.learnings
|
||
```
|
||
|
||
## Injected Prompt Files
|
||
|
||
### AGENTS.md
|
||
|
||
用途：多代理 workflows 与 delegation patterns。
|
||
|
||
```markdown
|
||
# Agent Coordination
|
||
|
||
## Delegation Rules
|
||
- 对开放式 codebase 问题使用 explore agent
|
||
- 对长时间任务启动 sub-agents
|
||
- 使用 sessions_send 做跨 session 通信
|
||
|
||
## Session Handoff
|
||
在委派给另一个 session 时：
|
||
1. 在 handoff message 中提供完整上下文
|
||
2. 包含相关文件路径
|
||
3. 指定期望的输出格式
|
||
```
|
||
|
||
### SOUL.md
|
||
|
||
用途：行为指导与沟通风格。
|
||
|
||
```markdown
|
||
# Behavioral Guidelines
|
||
|
||
## Communication Style
|
||
- 保持直接和简洁
|
||
- 避免不必要的 caveats 和 disclaimers
|
||
- 使用符合上下文的技术语言
|
||
|
||
## Error Handling
|
||
- 及时承认错误
|
||
- 立即给出更正后的信息
|
||
- 将重要 errors 记录到 learnings
|
||
```
|
||
|
||
### TOOLS.md
|
||
|
||
用途：工具能力、integration gotchas、本地配置。
|
||
|
||
```markdown
|
||
# Tool Knowledge
|
||
|
||
## Self-Improvement Skill
|
||
将 learnings 记录到 `.learnings/`，以支持持续改进。
|
||
|
||
## Local Tools
|
||
- 在这里记录 tool-specific gotchas
|
||
- 记录 authentication requirements
|
||
- 跟踪 integration quirks
|
||
```
|
||
|
||
## Learning Workflow
|
||
|
||
### Capturing Learnings
|
||
|
||
1. **In-session**：像平时一样记录到 `.learnings/`
|
||
2. **Cross-session**：提升到 workspace files
|
||
|
||
### Promotion Decision Tree
|
||
|
||
```
|
||
Is the learning project-specific?
|
||
├── Yes → Keep in .learnings/
|
||
└── No → Is it behavioral/style-related?
|
||
├── Yes → Promote to SOUL.md
|
||
└── No → Is it tool-related?
|
||
├── Yes → Promote to TOOLS.md
|
||
└── No → Promote to AGENTS.md (workflow)
|
||
```
|
||
|
||
### Promotion Format Examples
|
||
|
||
**From learning：**
|
||
> 在未配置 auth 的情况下执行 Git push 到 GitHub 会失败，并触发 desktop prompt
|
||
|
||
**To TOOLS.md：**
|
||
```markdown
|
||
## Git
|
||
- 在确认 auth 已配置前不要执行 push
|
||
- 使用 `gh auth status` 检查 GitHub CLI auth
|
||
```
|
||
|
||
## Inter-Agent Communication
|
||
|
||
OpenClaw 提供这些工具用于跨 session 通信：
|
||
|
||
### sessions_list
|
||
|
||
查看活跃和最近的 sessions：
|
||
```
|
||
sessions_list(activeMinutes=30, messageLimit=3)
|
||
```
|
||
|
||
### sessions_history
|
||
|
||
读取另一个 session 的 transcript：
|
||
```
|
||
sessions_history(sessionKey="session-id", limit=50)
|
||
```
|
||
|
||
### sessions_send
|
||
|
||
向另一个 session 发送消息：
|
||
```
|
||
sessions_send(sessionKey="session-id", message="Learning: API requires X-Custom-Header")
|
||
```
|
||
|
||
### sessions_spawn
|
||
|
||
启动一个后台 sub-agent：
|
||
```
|
||
sessions_spawn(task="Research X and report back", label="research")
|
||
```
|
||
|
||
## Available Hook Events
|
||
|
||
| Event | When It Fires |
|
||
|-------|---------------|
|
||
| `agent:bootstrap` | 在 workspace files 注入前触发 |
|
||
| `command:new` | 执行 `/new` command 时触发 |
|
||
| `command:reset` | 执行 `/reset` command 时触发 |
|
||
| `command:stop` | 执行 `/stop` command 时触发 |
|
||
| `gateway:startup` | gateway 启动时触发 |
|
||
|
||
## Detection Triggers
|
||
|
||
### Standard Triggers
|
||
- 用户纠正（"No, that's wrong..."）
|
||
- command failures（non-zero exit codes）
|
||
- API errors
|
||
- knowledge gaps
|
||
|
||
### OpenClaw-Specific Triggers
|
||
|
||
| Trigger | Action |
|
||
|---------|--------|
|
||
| Tool call error | 记录到 TOOLS.md，并标明 tool name |
|
||
| Session handoff confusion | 记录到 AGENTS.md，并补充 delegation pattern |
|
||
| Model behavior surprise | 记录到 SOUL.md，并说明 expected vs actual |
|
||
| Skill issue | 记录到 .learnings/ 或向上游反馈 |
|
||
|
||
## Verification
|
||
|
||
检查 hook 是否已注册：
|
||
|
||
```bash
|
||
openclaw hooks list
|
||
```
|
||
|
||
检查 skill 是否已加载：
|
||
|
||
```bash
|
||
openclaw status
|
||
```
|
||
|
||
## Troubleshooting
|
||
|
||
### Hook not firing
|
||
|
||
1. 确保 hooks 已在配置中启用
|
||
2. 修改配置后重启 gateway
|
||
3. 检查 gateway logs 中是否有 errors
|
||
|
||
### Learnings not persisting
|
||
|
||
1. 确认 `.learnings/` 目录存在
|
||
2. 检查文件权限
|
||
3. 确认 workspace path 配置正确
|
||
|
||
### Skill not loading
|
||
|
||
1. 检查 skill 是否位于 skills 目录中
|
||
2. 确认 SKILL.md 的 frontmatter 正确
|
||
3. 运行 `openclaw status` 查看已加载 skills
|