1# OpenClaw Integration
2 
3Complete setup and usage guide for integrating the self-improvement skill with OpenClaw.
4 
5## Overview
6 
7OpenClaw uses workspace-based prompt injection combined with event-driven hooks. Context is injected from workspace files at session start, and hooks can trigger on lifecycle events.
8 
9## Workspace Structure
10 
11```
12~/.openclaw/                      
13├── workspace/                   # Working directory
14│   ├── AGENTS.md               # Multi-agent coordination patterns
15│   ├── SOUL.md                 # Behavioral guidelines and personality
16│   ├── TOOLS.md                # Tool capabilities and gotchas
17│   ├── MEMORY.md               # Long-term memory (main session only)
18│   └── memory/                 # Daily memory files
19│       └── YYYY-MM-DD.md
20├── skills/                      # Installed skills
21│   └── <skill-name>/
22│       └── SKILL.md
23└── hooks/                       # Custom hooks
24    └── <hook-name>/
25        ├── HOOK.md
26        └── handler.ts
27```
28 
29## Quick Setup
30 
31### 1. Install the Skill
32 
33```bash
34clawdhub install self-improving-agent
35```
36 
37Or copy manually:
38 
39```bash
40cp -r self-improving-agent ~/.openclaw/skills/
41```
42 
43### 2. Install the Hook (Optional)
44 
45Copy the hook to OpenClaw's hooks directory:
46 
47```bash
48cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement
49```
50 
51Enable the hook:
52 
53```bash
54openclaw hooks enable self-improvement
55```
56 
57### 3. Create Learning Files
58 
59Create the `.learnings/` directory in your workspace:
60 
61```bash
62mkdir -p ~/.openclaw/workspace/.learnings
63```
64 
65Or in the skill directory:
66 
67```bash
68mkdir -p ~/.openclaw/skills/self-improving-agent/.learnings
69```
70 
71## Injected Prompt Files
72 
73### AGENTS.md
74 
75Purpose: Multi-agent workflows and delegation patterns.
76 
77```markdown
78# Agent Coordination
79 
80## Delegation Rules
81- Use explore agent for open-ended codebase questions
82- Spawn sub-agents for long-running tasks
83- Use sessions_send for cross-session communication
84 
85## Session Handoff
86When delegating to another session:
871. Provide full context in the handoff message
882. Include relevant file paths
893. Specify expected output format
90```
91 
92### SOUL.md
93 
94Purpose: Behavioral guidelines and communication style.
95 
96```markdown
97# Behavioral Guidelines
98 
99## Communication Style
100- Be direct and concise
101- Avoid unnecessary caveats and disclaimers
102- Use technical language appropriate to context
103 
104## Error Handling
105- Admit mistakes promptly
106- Provide corrected information immediately
107- Log significant errors to learnings
108```
109 
110### TOOLS.md
111 
112Purpose: Tool capabilities, integration gotchas, local configuration.
113 
114```markdown
115# Tool Knowledge
116 
117## Self-Improvement Skill
118Log learnings to `.learnings/` for continuous improvement.
119 
120## Local Tools
121- Document tool-specific gotchas here
122- Note authentication requirements
123- Track integration quirks
124```
125 
126## Learning Workflow
127 
128### Capturing Learnings
129 
1301. **In-session**: Log to `.learnings/` as usual
1312. **Cross-session**: Promote to workspace files
132 
133### Promotion Decision Tree
134 
135```
136Is the learning project-specific?
137├── Yes → Keep in .learnings/
138└── No → Is it behavioral/style-related?
139    ├── Yes → Promote to SOUL.md
140    └── No → Is it tool-related?
141        ├── Yes → Promote to TOOLS.md
142        └── No → Promote to AGENTS.md (workflow)
143```
144 
145### Promotion Format Examples
146 
147**From learning:**
148> Git push to GitHub fails without auth configured - triggers desktop prompt
149 
150**To TOOLS.md:**
151```markdown
152## Git
153- Don't push without confirming auth is configured
154- Use `gh auth status` to check GitHub CLI auth
155```
156 
157## Inter-Agent Communication
158 
159OpenClaw provides tools for cross-session communication:
160 
161Use these only when cross-session sharing is explicitly needed and the environment is trusted. Prefer short sanitized summaries over raw transcripts, command output, or secret-bearing content.
162 
163### sessions_list
164 
165View active and recent sessions:
166```
167sessions_list(activeMinutes=30, messageLimit=3)
168```
169 
170### sessions_history
171 
172Read transcript from another session:
173```
174sessions_history(sessionKey="session-id", limit=50)
175```
176 
177Only read another session's transcript when the user explicitly wants shared context or continuation across sessions.
178 
179### sessions_send
180 
181Send message to another session:
182```
183sessions_send(sessionKey="session-id", message="Learning: API requires X-Custom-Header")
184```
185 
186Prefer sending a concise learning summary plus relevant paths rather than forwarding raw transcript content.
187 
188### sessions_spawn
189 
190Spawn a background sub-agent:
191```
192sessions_spawn(task="Research X and report back", label="research")
193```
194 
195## Available Hook Events
196 
197| Event | When It Fires |
198|-------|---------------|
199| `agent:bootstrap` | Before workspace files inject |
200| `command:new` | When `/new` command issued |
201| `command:reset` | When `/reset` command issued |
202| `command:stop` | When `/stop` command issued |
203| `gateway:startup` | When gateway starts |
204 
205## Detection Triggers
206 
207### Standard Triggers
208- User corrections ("No, that's wrong...")
209- Command failures (non-zero exit codes)
210- API errors
211- Knowledge gaps
212 
213### OpenClaw-Specific Triggers
214 
215| Trigger | Action |
216|---------|--------|
217| Tool call error | Log to TOOLS.md with tool name |
218| Session handoff confusion | Log to AGENTS.md with delegation pattern |
219| Model behavior surprise | Log to SOUL.md with expected vs actual |
220| Skill issue | Log to .learnings/ or report upstream |
221 
222## Verification
223 
224Check hook is registered:
225 
226```bash
227openclaw hooks list
228```
229 
230Check skill is loaded:
231 
232```bash
233openclaw status
234```
235 
236## Troubleshooting
237 
238### Hook not firing
239 
2401. Ensure hooks enabled in config
2412. Restart gateway after config changes
2423. Check gateway logs for errors
243 
244### Learnings not persisting
245 
2461. Verify `.learnings/` directory exists
2472. Check file permissions
2483. Ensure workspace path is configured correctly
249 
250### Skill not loading
251 
2521. Check skill is in skills directory
2532. Verify SKILL.md has correct frontmatter
2543. Run `openclaw status` to see loaded skills
255