Skip to content

Commit 63bbbd9

Browse files
authored
Merge pull request #15 from codejunkie99/fix/openclaw-auto-wire
fix(openclaw): auto-wire AGENTS.md + register project agent
2 parents a397568 + c3605b3 commit 63bbbd9

6 files changed

Lines changed: 247 additions & 29 deletions

File tree

README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -194,7 +194,7 @@ adapters/ # one small shim per harness
194194
├── cursor/ (.cursor/rules/*.mdc)
195195
├── windsurf/ (.windsurfrules)
196196
├── opencode/ (AGENTS.md + opencode.json)
197-
├── openclaw/ (system-prompt include)
197+
├── openclaw/ (AGENTS.md + system-prompt include; auto-registers per-project agent)
198198
├── hermes/ (AGENTS.md)
199199
├── pi/ (AGENTS.md + .pi/skills symlink)
200200
├── standalone-python/ (DIY conductor entrypoint)
@@ -222,7 +222,7 @@ verify_codex_fixes.py # v0.8.0 regression checks (33 checks)
222222
| **Cursor** | `.cursor/rules/*.mdc` | no (manual reflect calls) |
223223
| **Windsurf** | `.windsurfrules` | no (manual reflect calls) |
224224
| **OpenCode** | `AGENTS.md` + `opencode.json` | partial (permission rules) |
225-
| **OpenClaw** | system-prompt include | varies by fork |
225+
| **OpenClaw** | `AGENTS.md` (auto-injected) + per-project `openclaw agents add --workspace` | varies by fork |
226226
| **Hermes Agent** | `AGENTS.md` (agentskills.io compatible) | partial (own memory) |
227227
| **Pi Coding Agent** | `AGENTS.md` + `.pi/skills/` | no (extension system) |
228228
| **Standalone Python** | `run.py` (any LLM) | yes (full control) |

adapters/openclaw/AGENTS.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# AGENTS.md — OpenClaw adapter for agentic-stack
2+
3+
OpenClaw auto-injects `AGENTS.md` from the workspace root into the system
4+
prompt. This file points it at the portable brain in `.agent/`.
5+
6+
## Startup (read in order)
7+
1. `.agent/AGENTS.md` — the map
8+
2. `.agent/memory/personal/PREFERENCES.md` — user conventions
9+
3. `.agent/memory/semantic/LESSONS.md` — distilled lessons
10+
4. `.agent/protocols/permissions.md` — hard rules
11+
12+
## Skills
13+
- Read `.agent/skills/_index.md` first.
14+
- Load `.agent/skills/<name>/SKILL.md` only when triggers match.
15+
16+
## Recall before non-trivial tasks
17+
For deploy / ship / migration / schema / timestamp / date / failing test /
18+
debug / refactor, FIRST run:
19+
20+
```bash
21+
python3 .agent/tools/recall.py "<description>"
22+
```
23+
24+
Surface results in a `Consulted lessons before acting:` block and follow
25+
them.
26+
27+
## Memory discipline
28+
- Update `.agent/memory/working/WORKSPACE.md` as you work.
29+
- After significant actions, run
30+
`python3 .agent/tools/memory_reflect.py <skill> <action> <outcome>`.
31+
- Never delete memory entries; archive only.
32+
- Quick state: `python3 .agent/tools/show.py`.
33+
- Teach a rule in one shot:
34+
`python3 .agent/tools/learn.py "<rule>" --rationale "<why>"`.
35+
36+
## Hard rules
37+
- No force push to `main`, `production`, or `staging`.
38+
- No modification of `.agent/protocols/permissions.md`.
39+
- Blocked means blocked.

adapters/openclaw/README.md

Lines changed: 35 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,50 @@
11
# OpenClaw adapter
22

3-
## Install
4-
OpenClaw doesn't have a project-root convention file the way Claude Code
5-
or Cursor does. Two options:
3+
OpenClaw auto-injects `AGENTS.md` (and `SOUL.md`, `MEMORY.md`, etc.) from
4+
the **workspace root** into the system prompt. The only catch: OpenClaw's
5+
default workspace is `~/.openclaw/workspace`, not the project you ran
6+
`install.sh` from. So wiring the brain is two things:
7+
8+
1. Drop an `AGENTS.md` at the project root that points at `.agent/`.
9+
2. Register a project-scoped OpenClaw agent whose workspace IS the project.
610

7-
**Option A (recommended):** Point OpenClaw at the config file:
11+
`./install.sh openclaw` does both automatically.
812

13+
## Install
914
```bash
10-
cp adapters/openclaw/config.md ./.openclaw-system.md
11-
# then configure OpenClaw to load this as its system prompt
15+
./install.sh openclaw
1216
```
1317

14-
**Option B:** Paste the contents of `config.md` into OpenClaw's system
15-
prompt settings directly.
18+
What it drops into `$TARGET`:
19+
- `AGENTS.md` — auto-injected by OpenClaw (skipped if you already have one
20+
that references `.agent/`)
21+
- `.openclaw-system.md` — backward-compat include for forks that take a
22+
`--system-prompt-file` flag
23+
- A registered OpenClaw agent named `<basename>-<hash>` with
24+
`--workspace <abs-path>`
1625

17-
Or:
26+
If `openclaw` isn't on PATH, the installer still writes the files and
27+
prints the exact `openclaw agents add` command to run later.
28+
29+
## Run
1830
```bash
19-
./install.sh openclaw
31+
openclaw --agent <basename>-<hash>
2032
```
2133

22-
## What it wires up
23-
A system-prompt include that instructs the agent to treat `.agent/` as
24-
authoritative on every session.
34+
The exact agent name is printed at the end of the install.
2535

2636
## Verify
27-
Ask "Read my lessons file." — it should open `.agent/memory/semantic/LESSONS.md`.
37+
Ask "Read my lessons file." — the agent should open
38+
`.agent/memory/semantic/LESSONS.md`.
39+
40+
## If AGENTS.md already exists in your project
41+
The installer won't overwrite it. It detects whether the existing file
42+
already references `.agent/`:
43+
- Already references `.agent/` → leaves it alone.
44+
- Doesn't → prints a snippet you can paste in to wire the brain.
2845

2946
## Notes
30-
OpenClaw varies by version; some forks support `.openclaw/` folders,
31-
others use a single config file. Check your version's docs for where to
32-
point the system prompt.
47+
OpenClaw varies by version; older forks may not support `agents add` or
48+
may expect a different flag. The `.openclaw-system.md` file is provided
49+
as a fallback you can point at with `--system-prompt-file` or paste into
50+
settings directly. Check your version's docs.

docs/per-harness/openclaw.md

Lines changed: 43 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,56 @@
11
# OpenClaw setup
22

33
## What the adapter installs
4-
- `.openclaw-system.md` at project root (to be used as the system prompt)
4+
- `AGENTS.md` at project root — OpenClaw auto-injects this from the
5+
workspace. Skipped if an existing `AGENTS.md` already references
6+
`.agent/`; a mergeable snippet is printed if not.
7+
- `.openclaw-system.md` at project root — backward-compat include for
8+
older forks / `--system-prompt-file` flows.
9+
- A registered OpenClaw agent named `<basename>-<hash>` with
10+
`--workspace <abs-path-of-project>` so OpenClaw treats the project
11+
(not `~/.openclaw/workspace`) as the workspace.
512

613
## Install
714
```bash
815
./install.sh openclaw
916
```
1017

11-
Then configure OpenClaw to load `.openclaw-system.md` as its system
12-
prompt. The exact steps vary by OpenClaw fork/version — check the docs.
18+
Then:
19+
```bash
20+
openclaw --agent <basename>-<hash>
21+
```
22+
23+
The exact agent name is printed at the end of the install output.
1324

1425
## How it works
15-
OpenClaw doesn't enforce a project-root convention file; instead, you
16-
paste the system prompt include (or point the config at it). The content
17-
mirrors the other adapters: read `.agent/` first, respect permissions,
18-
log after actions.
26+
OpenClaw reads its workspace bootstrap files (`AGENTS.md`, `SOUL.md`,
27+
`MEMORY.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`,
28+
`BOOTSTRAP.md`) verbatim into the system prompt. The installed
29+
`AGENTS.md` tells the agent to consult `.agent/` — memory, skills,
30+
protocols — on every session.
31+
32+
OpenClaw's default workspace is `~/.openclaw/workspace`, not the current
33+
directory. The installer registers a per-project agent
34+
(`openclaw agents add <name> --workspace <abs-path>`) so the workspace
35+
resolves to the project and the `.agent/` brain is visible.
36+
37+
## If `openclaw` isn't on PATH
38+
The installer still writes `AGENTS.md` and `.openclaw-system.md`, then
39+
prints the exact `openclaw agents add` command to run once you've
40+
installed OpenClaw.
41+
42+
## Re-running `install.sh`
43+
Safe. The `.agent/` brain is left alone if present. `AGENTS.md` is
44+
re-detected (no overwrite). Re-registering the same agent name against
45+
the same workspace is a no-op for compatible OpenClaw versions; older
46+
versions may error — that's surfaced in the install output.
1947

2048
## Troubleshooting
21-
- If the agent doesn't follow the instructions, make sure the file is
22-
actually being loaded (some forks require an explicit path, not auto-
23-
discovery).
49+
- Agent runs but ignores `.agent/`: confirm the agent's workspace with
50+
`openclaw agents list` or `openclaw config edit`. It should match the
51+
absolute path of your project.
52+
- `openclaw agents add` fails: your OpenClaw version may not support
53+
`--workspace`. Fall back to `.openclaw-system.md` via
54+
`--system-prompt-file .openclaw-system.md`.
55+
- You see `AGENTS.md already references .agent/ — leaving alone`: that's
56+
intentional. An earlier install (or another adapter) already wired it.

install.ps1

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,75 @@ switch ($Adapter) {
6767
Copy-Item (Join-Path $Src 'opencode.json') (Join-Path $TargetDir 'opencode.json') -Force
6868
}
6969
'openclaw' {
70+
# 1. Backward-compat: drop the system-prompt include
7071
Copy-Item (Join-Path $Src 'config.md') (Join-Path $TargetDir '.openclaw-system.md') -Force
72+
Write-Host " + .openclaw-system.md (system-prompt include; backward compat)"
73+
74+
# 2. OpenClaw auto-injects AGENTS.md from the workspace root.
75+
# Safely handle an existing AGENTS.md (codex/aider/cline also use it).
76+
$ocAgentsPath = Join-Path $TargetDir 'AGENTS.md'
77+
$ocTemplate = Join-Path $Src 'AGENTS.md'
78+
if (Test-Path $ocAgentsPath -PathType Leaf) {
79+
$ocExisting = Get-Content -Path $ocAgentsPath -Raw -ErrorAction SilentlyContinue
80+
if ($ocExisting -match '\.agent/') {
81+
Write-Host " ~ AGENTS.md already references .agent/ — leaving alone"
82+
} else {
83+
Write-Host " ! AGENTS.md exists but does not reference .agent/; not overwriting."
84+
Write-Host " merge this block into your AGENTS.md to wire the brain:"
85+
Write-Host " ---8<---"
86+
Get-Content -Path $ocTemplate | ForEach-Object { Write-Host " $_" }
87+
Write-Host " --->8---"
88+
}
89+
} else {
90+
Copy-Item $ocTemplate $ocAgentsPath -Force
91+
Write-Host " + AGENTS.md (auto-injected by OpenClaw from the workspace root)"
92+
}
93+
94+
# 3. Register a project-scoped OpenClaw agent so its workspace == this project.
95+
$ocAbs = (Resolve-Path $TargetDir).Path
96+
$ocBnRaw = Split-Path -Leaf $ocAbs
97+
# lowercase first (OpenClaw normalizes agent ids to lowercase), then sanitize
98+
$ocBnSafe = ($ocBnRaw.ToLower() -replace '[^a-z0-9._-]', '-') -replace '-+', '-'
99+
$ocBnSafe = $ocBnSafe.Trim('-')
100+
if ([string]::IsNullOrEmpty($ocBnSafe)) { $ocBnSafe = 'project' }
101+
# 6-hex-char SHA1 suffix of the absolute path for cross-project uniqueness
102+
$ocSha = [System.Security.Cryptography.SHA1]::Create()
103+
$ocBytes = [System.Text.Encoding]::UTF8.GetBytes($ocAbs)
104+
$ocHashHex = -join (($ocSha.ComputeHash($ocBytes)) | ForEach-Object { $_.ToString('x2') })
105+
$ocAgentName = "$ocBnSafe-$($ocHashHex.Substring(0,6))"
106+
107+
$ocBin = Get-Command openclaw -ErrorAction SilentlyContinue
108+
if ($ocBin) {
109+
Write-Host " → registering OpenClaw agent '$ocAgentName' (workspace: $ocAbs)"
110+
try {
111+
$ocOut = & openclaw agents add $ocAgentName --workspace $ocAbs 2>&1
112+
$ocRc = $LASTEXITCODE
113+
$ocOut | ForEach-Object { Write-Host " $_" }
114+
$ocOutJoined = ($ocOut | Out-String)
115+
if ($ocRc -eq 0) {
116+
Write-Host " ✓ registered. run from anywhere: openclaw --agent $ocAgentName"
117+
} elseif ($ocOutJoined -match '(?i)already exists') {
118+
Write-Host " ✓ already registered (idempotent re-run). run: openclaw --agent $ocAgentName"
119+
} else {
120+
Write-Host " ! 'openclaw agents add' failed (details above)."
121+
Write-Host " if your OpenClaw fork does not support 'agents add --workspace',"
122+
Write-Host " fall back to the system-prompt include we wrote:"
123+
Write-Host " openclaw --system-prompt-file `"$ocAbs\.openclaw-system.md`""
124+
Write-Host " otherwise retry: openclaw agents add `"$ocAgentName`" --workspace `"$ocAbs`""
125+
}
126+
} catch {
127+
Write-Host " ! 'openclaw agents add' errored: $_"
128+
Write-Host " fall back to the system-prompt include:"
129+
Write-Host " openclaw --system-prompt-file `"$ocAbs\.openclaw-system.md`""
130+
Write-Host " or retry: openclaw agents add `"$ocAgentName`" --workspace `"$ocAbs`""
131+
}
132+
} else {
133+
Write-Host " ! 'openclaw' CLI not found on PATH. after installing OpenClaw, try:"
134+
Write-Host " openclaw agents add `"$ocAgentName`" --workspace `"$ocAbs`""
135+
Write-Host " openclaw --agent $ocAgentName"
136+
Write-Host " or, on forks without 'agents add', use the system-prompt include:"
137+
Write-Host " openclaw --system-prompt-file `"$ocAbs\.openclaw-system.md`""
138+
}
71139
}
72140
'hermes' {
73141
Copy-Item (Join-Path $Src 'AGENTS.md') (Join-Path $TargetDir 'AGENTS.md') -Force

install.sh

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,67 @@ case "$ADAPTER" in
5959
cp "$SRC/opencode.json" "$TARGET/opencode.json"
6060
;;
6161
openclaw)
62+
# 1. Backward-compat: drop the system-prompt include for users on older
63+
# OpenClaw flows that require pasting or --system-prompt-file.
6264
cp "$SRC/config.md" "$TARGET/.openclaw-system.md"
65+
echo " + .openclaw-system.md (system-prompt include; backward compat)"
66+
67+
# 2. OpenClaw auto-injects AGENTS.md from the workspace root. Drop it
68+
# safely, the same way pi does — don't stomp an existing AGENTS.md
69+
# (codex/aider/amp/cline all use this filename).
70+
if [[ -f "$TARGET/AGENTS.md" ]]; then
71+
if grep -q '\.agent/' "$TARGET/AGENTS.md" 2>/dev/null; then
72+
echo " ~ AGENTS.md already references .agent/ — leaving alone"
73+
else
74+
echo " ! AGENTS.md exists but does not reference .agent/; not overwriting."
75+
echo " merge this block into your AGENTS.md to wire the brain:"
76+
echo " ---8<---"
77+
sed 's/^/ /' "$SRC/AGENTS.md"
78+
echo " --->8---"
79+
fi
80+
else
81+
cp "$SRC/AGENTS.md" "$TARGET/AGENTS.md"
82+
echo " + AGENTS.md (auto-injected by OpenClaw from the workspace root)"
83+
fi
84+
85+
# 3. Register a project-scoped OpenClaw agent whose workspace IS this
86+
# project. Without this, OpenClaw's workspace defaults to
87+
# ~/.openclaw/workspace and never sees the .agent/ brain.
88+
OC_ABS="$(cd "$TARGET" && pwd)"
89+
OC_BN_RAW="$(basename "$OC_ABS")"
90+
# lowercase first (OpenClaw normalizes agent ids to lowercase), then
91+
# sanitize to [a-z0-9._-], collapse dashes, trim
92+
OC_BN_SAFE="$(printf '%s' "$OC_BN_RAW" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9._-' '-' | sed 's/-\{2,\}/-/g; s/^-//; s/-$//')"
93+
[[ -z "$OC_BN_SAFE" ]] && OC_BN_SAFE="project"
94+
# 6-digit stable suffix from absolute path so cross-project collisions
95+
# (api, backend, app, website) resolve to distinct agent names
96+
OC_PATH_CKSUM="$(printf '%s' "$OC_ABS" | cksum | awk '{print $1}')"
97+
OC_AGENT_NAME="${OC_BN_SAFE}-$(printf '%06d' "$((OC_PATH_CKSUM % 1000000))")"
98+
99+
if command -v openclaw >/dev/null 2>&1; then
100+
echo " → registering OpenClaw agent '$OC_AGENT_NAME' (workspace: $OC_ABS)"
101+
# capture stdout+stderr and rc without tripping set -e
102+
OC_RC=0
103+
OC_OUT="$(openclaw agents add "$OC_AGENT_NAME" --workspace "$OC_ABS" 2>&1)" || OC_RC=$?
104+
printf '%s\n' "$OC_OUT" | sed 's/^/ /'
105+
if [[ $OC_RC -eq 0 ]]; then
106+
echo " ✓ registered. run from anywhere: openclaw --agent $OC_AGENT_NAME"
107+
elif printf '%s' "$OC_OUT" | grep -qi "already exists"; then
108+
echo " ✓ already registered (idempotent re-run). run: openclaw --agent $OC_AGENT_NAME"
109+
else
110+
echo " ! 'openclaw agents add' failed (details above)."
111+
echo " if your OpenClaw fork does not support 'agents add --workspace',"
112+
echo " fall back to the system-prompt include we wrote:"
113+
echo " openclaw --system-prompt-file \"$OC_ABS/.openclaw-system.md\""
114+
echo " otherwise retry: openclaw agents add \"$OC_AGENT_NAME\" --workspace \"$OC_ABS\""
115+
fi
116+
else
117+
echo " ! 'openclaw' CLI not found on PATH. after installing OpenClaw, try:"
118+
echo " openclaw agents add \"$OC_AGENT_NAME\" --workspace \"$OC_ABS\""
119+
echo " openclaw --agent $OC_AGENT_NAME"
120+
echo " or, on forks without 'agents add', use the system-prompt include:"
121+
echo " openclaw --system-prompt-file \"$OC_ABS/.openclaw-system.md\""
122+
fi
63123
;;
64124
hermes)
65125
cp "$SRC/AGENTS.md" "$TARGET/AGENTS.md"

0 commit comments

Comments
 (0)