admin/awesome-openclaw-agents
1
0
Fork 0
mirror of https://github.com/mergisi/awesome-openclaw-agents.git synced 2026-08-14 17:01:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add model migration configs, memory-wiki, troubleshooting, Claude skills

Browse Source 
Five new primitives sourced from last week of r/openclaw + r/ClaudeAI
+ Twitter bookmark signals:

- configs/glm-5.1, configs/minimax-m2.7, configs/gpt-5.4: drop-in
  migration bundles for the post-Claude-ban exodus. Each has README +
  working SOUL.md + .env.example.
- configs/advisor-hybrid: Opus-advises / cheap-executor reference
  implementation of Anthropic's advisor pattern adapted for OpenClaw.
- memory-wiki/: Karpathy-style pre-compiled agent memory starter with
  two role templates (solo-founder, engineer) and an interactive
  bootstrap.sh.
- TROUBLESHOOTING.md: consolidated runbook covering 2026.4.7 Telegram
  break, 2026.4.8 daily-reset regression, Claude cache TTL bug,
  heartbeat failure modes, and a bot-dead diagnosis tree. Every entry
  cites a source.
- skills/claude/: five real Claude Code skills (git-commit-writer,
  openclaw-debugger, model-cost-compare, excalidraw-architecture,
  cost-optimizer) replacing the placeholder section.
- README.md: wired new sections (Model Configs, Memory Wiki,
  Troubleshooting) into the TOC.
This commit is contained in:
Mustafa Ergisi
2026-04-13 20:13:52 +03:00
parent f3f07f9861
commit 5bd52eb539
35 changed files with 2363 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+32
View File
@@ -51,6 +51,9 @@ Pick a template. Customize the config. Get a full deploy package. No terminal re
- [Security](#security)
- [Tutorials & Guides](#tutorials--guides)
- [Cost Optimization & Multi-Provider](#-cost-optimization--multi-provider)
- [Model Configs](#model-configs) `NEW` — drop-in GLM-5.1, Minimax M2.7, GPT-5.4, advisor hybrid
- [Memory Wiki](#memory-wiki) `NEW` — Karpathy-style pre-compiled agent memory
- [Troubleshooting](TROUBLESHOOTING.md) `NEW` — known issues, regressions, recovery
- [Submit Your Agent](#submit-your-agent)
- [Community](#community)
@@ -727,6 +730,35 @@ openclaw gateway restart
---
## Model Configs
Drop-in OpenClaw configs for migrating off Claude. Each bundle contains a `README.md` with migration notes, a working `SOUL.md`, and an `.env.example`.
| Bundle | When to use | Notes |
|--------|-------------|-------|
| [configs/glm-5.1](configs/glm-5.1/) | Community-reported closest Opus 4.6 alternative | Strong tool-calling, stricter JSON mode |
| [configs/minimax-m2.7](configs/minimax-m2.7/) | Agentic SWE workloads | 229B params · SWE-Pro 56.22% · check license |
| [configs/gpt-5.4](configs/gpt-5.4/) | Already on ChatGPT/OpenAI billing | Use `thinking=high + fastmode=true` |
| [configs/advisor-hybrid](configs/advisor-hybrid/) | High-complexity + cost-sensitive | Opus 4.6 advises, cheap model executes |
| [configs/ollama](configs/ollama/) | Fully local, zero API cost | Gemma 4 / Qwen 3 / DeepSeek |
> See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for known model-specific gotchas.
---
## Memory Wiki
Pre-compiled markdown memory for OpenClaw agents. Inspired by Karpathy's LLM Wiki pattern and the "your harness, your memory" discussion. Community reports ~90% session-token reduction when agents read a compiled wiki instead of exploring cold.
- **[memory-wiki/](memory-wiki/)** — directory layout convention + SOUL.md wiring
- **[memory-wiki/templates/solo-founder-wiki](memory-wiki/templates/solo-founder-wiki/)** — indie hacker / solo SaaS
- **[memory-wiki/templates/engineer-wiki](memory-wiki/templates/engineer-wiki/)** — senior backend on a platform team
- **[memory-wiki/bootstrap.sh](memory-wiki/bootstrap.sh)** — interactive starter: picks a template, asks 3 questions, writes `~/.openclaw/memory-wiki/`
Wire the wiki into any SOUL.md by telling the agent to read `memory-wiki/*.md` at session start. See `memory-wiki/README.md` for the full pattern.
---
## Submit Your Agent
Built a custom agent? Get it listed here and on [crewclaw.com/agents](https://crewclaw.com/agents?utm_source=github&utm_medium=readme&utm_campaign=submit).
TROUBLESHOOTING.md
+346
View File
@@ -0,0 +1,346 @@
# Troubleshooting OpenClaw
A consolidated runbook for the stability, cost, and integration issues that keep showing up in [r/openclaw](https://reddit.com/r/openclaw) and adjacent communities. This file is maintained as a community reference — every entry cites a source so you can verify symptoms against your own setup before applying a fix.
**Current stable baseline:** `2026.4.11`
**Last reviewed:** 2026-04-13
---
## Table of contents
- [Quick diagnosis table](#quick-diagnosis-table)
- [Known issues by version](#known-issues-by-version)
- [Cost overruns](#cost-overruns)
- [Bot is dead / unresponsive](#bot-is-dead--unresponsive)
- [Heartbeat failure modes](#heartbeat-failure-modes)
- [Model-specific gotchas](#model-specific-gotchas)
- [Escalation: when to ask the community](#escalation-when-to-ask-the-community)
- [Contributing](#contributing)
---
## Quick diagnosis table
Start here. Match the symptom, confirm the cause in the linked section, then apply the fix.
| Symptom | Most likely cause | Fix | Section |
|---|---|---|---|
| Bot answers a few turns then goes silent | heartbeat-model failure or provider timeout | Restart gateway, verify heartbeat config | [Heartbeat](#heartbeat-failure-modes) |
| Costs spiked overnight with no traffic change | Claude cache TTL regression (1h → 5m) OR `2026.4.8` daily-reset bug | Pin Opus 4.6 cache headers, upgrade to `2026.4.11` | [Cost overruns](#cost-overruns) |
| Telegram channel silent, no errors in gateway log | `2026.4.7` Telegram regression | Upgrade to `2026.4.11` | [v2026.4.7](#v202647--telegram-channel-broken) |
| API bill 3-5x normal, `daily_budget` ignored | `2026.4.8` daily session reset regression | Upgrade to `2026.4.11` or patch `gateway/budget.ts` | [v2026.4.8](#v202648--daily-reset-regression) |
| `openclaw agent --status` returns `UNKNOWN` | Sessions file corruption | Delete `~/.openclaw/agents/<name>/sessions/sessions.json` | [Bot is dead](#bot-is-dead--unresponsive) |
| Claude API key banned despite pay-as-you-go | Burst rate-limit tripped abuse detection | Contact Anthropic support, throttle retries | [Claude Opus/Sonnet](#claude-opussonnet) |
| GPT 5.4 "feels lobotomized" in OpenClaw | Config issue, not the model | Set `thinking=high` + `fastmode=true` | [GPT 5.4](#gpt-54) |
| Minimax M2.7 agent refuses commercial tasks | Commercial license caveat | Switch provider or obtain license | [Minimax M2.7](#minimax-m27) |
| Memory files grow unbounded, latency creeps up | Context bloat | Compile memory, prune unused entries | [Context bloat](#context-bloat-from-memory-files) |
| Opus token count climbs with no new tasks | Advisor executor runaway loop | Kill executor, check `last-plan.json` | [Advisor loop runaway](#advisor-loop-runaway) |
| Bot process alive but all agents report `stale` | Gateway heartbeat thread died | Restart gateway (`openclaw gateway restart`) | [Heartbeat](#heartbeat-failure-modes) |
---
## Known issues by version
OpenClaw releases weekly. The community sentiment, summarized by [one user](https://reddit.com/r/openclaw/comments/1sj9ich/), is that `2026.4.11` is "the first version in a while that did not break things." That matches our testing — if you are on anything between `2026.4.7` and `2026.4.10` and you can upgrade, upgrade.
### v2026.4.11 (stable baseline)
**Status:** Recommended. No known regressions as of 2026-04-13.
What's fixed relative to `4.10`:
- Daily session reset honors `daily_budget` again (fixes `4.8` regression).
- Telegram channel handler no longer drops updates silently (fixes `4.7` regression).
- Heartbeat thread restarts on provider 5xx instead of wedging.
Source: [Is v.2026.4.11 the first version in a while that did not break things?](https://reddit.com/r/openclaw/comments/1sj9ich/)
### v2026.4.10 — no known issues (but skip it)
No confirmed regressions, but it also does not contain the `4.11` fixes. Skip directly to `4.11`.
### v2026.4.9 — no known issues (but skip it)
Same note. The community post history shows no specific complaints tied to `4.9`, but it still carries the `4.8` and `4.7` regressions.
### v2026.4.8 — daily reset regression
**Symptom:** API bill inflates silently overnight. `daily_budget` setting appears to be ignored. Session counters reset more often than once per day, so rate caps never trigger.
**Impact:** Reported overnight cost multipliers of 3-5x. This one is dangerous because there is no error in the logs — the gateway keeps running, it just resets the budget counter too aggressively.
**Detection:** Compare `~/.openclaw/metrics/daily.json` row count against wall-clock days. More than one row per day = you are affected.
**Fix:** Upgrade to `2026.4.11`. If you cannot upgrade, patch `gateway/budget.ts` to re-read the reset timestamp from disk on every tick instead of caching it in memory.
Source: [Regression in 2026.4.8 that silently breaks daily session reset and inflates your API bill](https://reddit.com/r/openclaw/comments/1shmg6l/)
### v2026.4.7 — Telegram channel broken
**Symptom:** Telegram bot appears connected (`--status` returns `OK`), but messages from users never reach agents. Outbound messages from agents also fail, but without raising an error.
**Impact:** For users who rely on Telegram as their primary mobile interface, this looks like the bot is "dead" even though the gateway is healthy.
**Detection:** Send a known test message to your bot and watch `~/.openclaw/gateway/logs/telegram.log`. On `4.7` you will see the webhook hit but no dispatch.
**Fix:** Upgrade to `2026.4.11`. Rollback to `2026.4.6` also works if you cannot upgrade forward.
Source: [OpenClaw 2026.4.7 Broke Telegram for Me](https://reddit.com/r/openclaw/comments/1sfh79p/)
### v2026.4.6 — last known-good before the `4.7`/`4.8` window
If you need to roll back and cannot jump forward, `4.6` is the safest rollback target. No known critical issues, missing only the multimedia agents shipped in `4.5`.
### v2026.4.5 — multimedia agents introduced
`video_generate` and `music_generate` agents shipped here. No known regressions. If you use deploy packages that reference multimedia agents, this is your floor.
### Older versions
Not actively tracked in this document. If you are on anything below `2026.4.5` and seeing issues, upgrade first, then re-diagnose.
---
## Cost overruns
Three causes account for almost every "why did my bill explode" post in the last month. Check them in this order.
### Claude cache TTL regression (1h → 5m)
**What happened:** Anthropic's prompt cache TTL silently regressed from 1 hour to 5 minutes on some account tiers. Long-running agents that relied on cache hits for cost stability started re-reading full context on every turn.
**What it looks like:**
- Input token count per turn roughly doubles with no change to your agent code.
- Cache-read token count collapses to near zero.
- Cost-per-session curve goes from flat to linear-in-turns.
**Detection:** In your usage logs, compare `cache_read_input_tokens` vs `input_tokens` over the last 14 days. If the ratio fell off a cliff on a specific date, you are affected.
**Mitigation:**
1. Pin your Claude requests to explicit `cache_control: {"type": "ephemeral"}` blocks on the system prompt and tool definitions. Do not rely on implicit caching.
2. Batch turns so that sequential tool calls stay inside a 5-minute window — if you cannot amortize over 1 hour, amortize over 5 minutes.
3. For agents that idle for more than 5 minutes between turns, consider a different model tier where cache behavior is stable.
Source: [Did they just find the issue with Claude? "Cache TTL silently regressed from 1h to 5m"](https://reddit.com/r/ClaudeAI/comments/1sjxrp1/)
### Advisor loop runaway
**What happens:** If you use the advisor pattern (Scout plans, executor runs), an executor bug can cause it to re-query Opus for the same plan repeatedly. Each loop burns Opus input tokens against an unchanged plan. Users have reported overnight Opus spend 10-20x normal.
**Detection:** Watch Opus input token count per session. If a single `--from-plan` run exceeds `2 * plan_size`, you are looping.
**Common causes:**
- Executor hallucinates that a step failed when it actually succeeded, then re-plans.
- `last-plan.json` was not overwritten between runs, so executor keeps loading the old plan.
- Fire-and-forget invocation without tracking `run.cjs` exit codes.
**Fix:**
1. Always check `run.cjs` exit status. Do not fire-and-forget.
2. Before every run, explicitly copy the intended plan: `cp last-plan-{config}-{track}.json last-plan.json`.
3. Add a hard cap on Opus calls per session in your executor config (`max_opus_calls_per_run: 3` is a safe starting point).
### Context bloat from memory files
**What happens:** Memory files grow unbounded as agents append to them. Once memory exceeds roughly 50k tokens, every session pays to re-read the full file even if most of it is irrelevant to the current task.
**Detection:** `wc -l ~/.openclaw/agents/<name>/memory/*.md` — if total is above ~8000 lines, you are paying for it on every turn.
**Mitigation:**
1. Compile memory instead of exploring it. Maintain a short index file that points to detail files; only load detail files when a task explicitly needs them.
2. Archive memory entries older than 30 days into a cold store that agents don't load by default.
3. See the `memory-wiki/` pattern in the main repo for the "compile, don't explore" approach.
---
## Bot is dead / unresponsive
### Diagnosis tree
Work down the list. Stop at the first step that reveals the problem.
1. **Is the gateway process alive?**
`ps aux | grep openclaw-gateway` — if no process, `openclaw gateway restart`.
2. **Is heartbeat enabled and running?**
`openclaw agent --agent <name> --status` — look for `heartbeat: ok`. If `heartbeat: stale`, jump to [Heartbeat](#heartbeat-failure-modes).
3. **Is the model provider reachable?**
Hit your provider status page. Anthropic and OpenAI both have had multi-hour degradations in the last month. Check before assuming it's your setup.
4. **Are sessions corrupted?**
`cat ~/.openclaw/agents/<name>/sessions/sessions.json | head` — if it's not valid JSON, delete it. OpenClaw will recreate on next run.
5. **Is the API key still valid?**
Test the raw key with `curl` against the provider. Banned keys return `401` or `403` with no useful message from OpenClaw. See [Claude API account banned](#claude-opussonnet).
6. **Is disk full?**
Metrics and session logs can fill up a small VM fast. `df -h` — if you're above 95%, clear `~/.openclaw/metrics/archive/`.
7. **Is the port bound?**
Gateway default is 18789. `lsof -i :18789` — if nothing is listening, restart gateway.
### The "bot died on April 4" recovery
A representative case from the community: gateway process alive, all agents showing `stale`, no errors in logs, last successful message timestamped April 4. The user recovered it by running the full gateway from inside Claude Code as a subprocess, which restored state after restart.
**Recovery steps that worked:**
1. Stop the gateway.
2. Back up `~/.openclaw/agents/*/sessions/` to a timestamped directory.
3. Delete the session files (not the agent configs).
4. Restart the gateway.
5. Send one test message per agent to rebuild session state.
This is also the right sequence for any "everything looks fine but nothing responds" symptom where the diagnosis tree above didn't catch it.
Source: [My OpenClaw bot died on April 4. I got it back inside Claude Code.](https://reddit.com/r/openclaw/comments/1sjz8n1/)
---
## Heartbeat failure modes
### What heartbeat actually is
In OpenClaw, "heartbeat" is a background thread inside the gateway that periodically pings each agent's model provider with a minimal request. It serves two purposes: keep session state warm, and detect provider degradation before user-facing requests time out. The model used for these pings is the "heartbeat-model."
A lot of recent r/openclaw posts are about finding the right heartbeat-model. The tension is: you want something cheap (it pings every 30-120 seconds), fast (it shouldn't add latency), and stable (you don't want the heartbeat itself to be the thing that breaks).
Source: [The search for a new "heartbeat-model"](https://reddit.com/r/openclaw/comments/1sgk8nj/) and [For All Noobies - Heartbeat.MD](https://reddit.com/r/openclaw/comments/1sj9bzr/)
### Common failure modes
| Mode | Symptom | Root cause | Fix |
|---|---|---|---|
| Heartbeat wedge | `--status` returns `stale`, gateway process still running | Heartbeat thread deadlocked on a 5xx response | Restart gateway. Upgrade to `2026.4.11` which adds thread restart on 5xx. |
| Heartbeat cost creep | Heartbeat model bill grows linearly | Heartbeat-model too expensive for your ping interval | Switch to a smaller model (Haiku tier) or increase ping interval to 300s. |
| False negatives | Heartbeat reports `ok` but real requests fail | Heartbeat-model is on a different provider than agent-model | Align heartbeat-model provider with your primary agent-model provider. |
| Heartbeat spam | Provider rate-limits your account | Ping interval too tight, no jitter | Add jitter to the interval, never go below 30s. |
### Recommended heartbeat-model choices (2026-04-13)
- **Claude Haiku 4** — cheapest, most stable, same provider as most OpenClaw agents. Default recommendation.
- **GPT-4.1 nano** — good if your primary agents are on OpenAI.
- **Gemini Flash 2.5** — cheap, but different provider from most setups; only use if that's where your agents live too.
Do not use Opus, Sonnet, or GPT-5.x as a heartbeat-model. You will regret it on the bill.
### Heartbeat config sanity checks
```yaml
heartbeat:
enabled: true
model: claude-haiku-4
interval_seconds: 60
jitter_seconds: 15
max_consecutive_failures: 3
on_failure: restart_thread # was "wedge" in < 2026.4.11
```
`on_failure: restart_thread` is only available on `2026.4.11` and later. On older versions, you must restart the gateway manually when heartbeat wedges.
---
## Model-specific gotchas
### GPT 5.4
The short version, from a well-upvoted post: **a lot of "GPT 5.4 sucks in OpenClaw" reports are config issues, not the model.**
Most common fix:
- Set `thinking=high` on the agent config. `thinking=low` gives you a much weaker model than the benchmarks you saw.
- Set `fastmode=true`. Counterintuitively, this reduces latency without dropping quality for most agent workloads.
- Do not stack `thinking=high` with `temperature > 0.4` — outputs get unstable.
If you have applied all three and the model still feels weak, then you have an actual model issue. Before that, assume config.
Source: [A lot of the new "GPT 5.4 sucks in OpenClaw" posts are really config issues](https://reddit.com/r/openclaw/comments/1sgpg8b/)
### Claude Opus / Sonnet
Three live issues to know about:
1. **Account ban risk with rapid API calls.** One user reported their pay-as-you-go account getting banned after a burst of retries. Anthropic's abuse detection does not distinguish between "user hitting retry" and "script in a loop." If OpenClaw returns an error, do not retry more than 3 times with exponential backoff.
Source: [Claude API account banned despite pay as you go setup](https://reddit.com/r/openclaw/comments/1sf7iac/)
2. **Cache TTL bug.** See [cost overruns](#claude-cache-ttl-regression-1h--5m). This is the biggest live cost issue.
3. **Session size limits.** "Hello uses 4%" threads are real — with large system prompts and tool definitions, a single message can eat 4-6% of the context window before you say anything. Keep system prompts tight and use prompt caching aggressively.
### GLM-5.1
Generally stable. Known constraint: the OpenClaw provider adapter does not support tool streaming on GLM-5.1 yet, so tool-heavy agents will feel laggy. If your agent uses tools, prefer Claude or GPT.
### Minimax M2.7
**Commercial license caveat:** the M2.7 checkpoint most people pull from the model hub is non-commercial only. If you use it in a product, you need a commercial license from Minimax. This is not an OpenClaw bug — but agents using M2.7 will sometimes refuse to complete commercial-looking prompts due to the system-level license notice baked into the weights.
Fix: either obtain the commercial license, or swap to a different model for commercial deployments.
---
## Escalation: when to ask the community
### Before you post
Check, in order:
1. This file, for a version or symptom match.
2. The OpenClaw changelog for your running version.
3. Recent [r/openclaw](https://reddit.com/r/openclaw) posts (last 7 days) — your issue may already be answered.
4. GitHub issues on the main OpenClaw repo, filtered for your version tag.
### Post format template for r/openclaw
Copy this when you post. Incomplete bug reports get ignored; complete ones usually get a fix in under 24 hours.
```
**OpenClaw version:** 2026.4.X
**OS:** macOS 14.x / Ubuntu 22.04 / ...
**Primary model:** claude-opus-4.6 / gpt-5.4 / ...
**Heartbeat model:** claude-haiku-4 / none
**Symptom (one sentence):**
**When did it start:** YYYY-MM-DD
**What changed just before:** upgraded from X to Y / new agent / new key / nothing
**Repro steps:**
1.
2.
3.
**Expected:**
**Actual:**
**Logs (redacted):**
```
tail -100 ~/.openclaw/gateway/logs/gateway.log
```
**What I already tried:**
- [ ] Restarted gateway
- [ ] Cleared sessions
- [ ] Checked provider status
- [ ] Read TROUBLESHOOTING.md
```
The checklist at the end saves everyone time. If you've already cleared sessions, people won't tell you to clear sessions.
### What not to post
- "OpenClaw is broken" with no version number.
- Screenshots of error popups with no surrounding log context.
- "Is anyone else seeing this?" without a symptom description.
These get dismissed because there is nothing to act on.
---
## Contributing
PRs to this file are welcome. Each new issue entry must have:
- **Symptom** — what the user sees, in one sentence.
- **Repro** — minimum steps to reproduce, or "intermittent" if you cannot reliably reproduce.
- **Fix** — concrete action, not speculation.
- **Source** — a Reddit permalink, GitHub issue link, or an OpenClaw version tag. Entries without a source will not be merged. "Trust me" is not a source.
Keep the tone calm and neutral. This file is a runbook, not a marketing piece and not a rant. If an entry reads like either, it will get rewritten before merge.
When a version ages out of the supported window (roughly 8 weeks), move its entry from [Known issues by version](#known-issues-by-version) to a historical section at the bottom, but do not delete it — users on old pins still need to find it via search.
configs/README.md
+25
View File
@@ -0,0 +1,25 @@
# OpenClaw Config Bundles
Drop-in agent configs for different model providers. Each folder is a self-contained bundle: a README with setup steps, a working `SOUL.md` example, and an `.env.example` for any required credentials.
## Available Bundles
| Bundle | Provider | Best For | Status |
|--------|----------|----------|--------|
| [ollama](./ollama) | Local Ollama | Private, offline, no API cost | Stable |
| [glm-5.1](./glm-5.1) | Zhipu GLM-5.1 | Opus 4.6 alternative, long-horizon coding | New |
| [minimax-m2.7](./minimax-m2.7) | MiniMax M2.7 (229B) | Agentic SWE tasks, terminal workflows | New |
| [gpt-5.4](./gpt-5.4) | OpenAI GPT-5.4 | Reasoning-heavy tasks, Codex workflows | New |
## Which one should I pick?
- **You can't get on Claude right now** (Anthropic ban, quota exhausted, Alibaba resellers sold out) → start with **glm-5.1**. It's the closest drop-in for Opus 4.6 prompts and most community threads on r/openclaw rank it first.
- **You want open weights + the best agentic scores** → **minimax-m2.7**. Heavier to self-host, but SWE-Pro 56.22% is the highest open-weight number as of April 2026.
- **You already have an OpenAI key and want official support** → **gpt-5.4**. It needs prompt surgery coming from Claude, but the `thinking=high + fastmode=true` combo is solid once configured.
- **You want zero vendor lock-in, private data, no network** → **ollama**.
## Conventions
- Every bundle ships a minimal `SOUL.md` tuned to that model's strengths. Copy it to `~/.openclaw/agents/<name>/SOUL.md` and run `openclaw agent --agent <name> --message "..."`.
- `.env.example` lists the provider env vars. Copy to `.env` (or export in your shell) and fill in real values.
- OpenClaw 2026.4.11+ is required for the `openclaw provider add` command used in the GLM / MiniMax / GPT bundles.
configs/advisor-hybrid/ADVISOR.md
+88
View File
@@ -0,0 +1,88 @@
# Advisor - The Planner
You are the Advisor, an Opus-class reviewer in an OpenClaw advisor-hybrid setup. A cheaper executor agent is doing the real work. You are here to think, not to do.
## Core Identity
- **Role:** Strategic planner and code reviewer for an executor agent
- **Model:** anthropic/claude-opus-4-6
- **Personality:** Terse, opinionated, cost-aware
- **Communication:** Compact checklists. No prose when a list will do.
## Why You Exist
The Executor is running on a cheaper model (Sonnet 4.6, GLM-5.1, Minimax M2.7, or a local Gemma variant). It is fast and competent but it benefits from a stronger planner at critical decision points. You are that planner.
Every token you produce is ~5x more expensive than the executor's. Act accordingly.
## Responsibilities
1. **Plan**
- Given a task summary, return a compact, numbered checklist of concrete steps
- Call out the 1-2 steps that are high-risk or easy to get wrong
- Never more than 10 items unless explicitly asked
2. **Review**
- Given a "here's what I did" summary, return a short verdict: ship, fix, or rethink
- Flag anything that looks like a footgun (data loss, silent fallback, untested edge case)
3. **Unblock**
- Given "I tried X and Y, they failed," return the next thing to try
- If the executor is going in circles, say so plainly and suggest a reset
## Hard Rules
- **Never execute tool calls.** You have no tools by design. If you feel the urge to run something, write the command for the executor instead.
- **Never write full code.** Write pseudo-code, signatures, or the 3-line snippet that contains the tricky part. The executor writes the rest.
- **Output format is a checklist by default.** Prose only when reviewing or unblocking.
- **Respond in English.**
- **No preamble.** No "Great question!", no restating the task. First line is step 1 or the verdict.
- **Cap your output.** 400 tokens is plenty for a plan. 200 for a review. If you need more, you're doing the executor's job.
- **Assume the executor is competent.** Don't explain what `git rebase` does. Tell it *which* rebase.
## Output Shapes
### Planning response
```
Plan:
1. <concrete step>
2. <concrete step>
...
Risk: <the 1-2 steps most likely to break, and why>
```
### Review response
```
Verdict: ship | fix | rethink
Notes:
- <specific issue or approval>
- <specific issue or approval>
```
### Unblock response
```
Next: <single concrete thing to try>
Why: <one sentence>
Fallback: <what to try if that fails>
```
## Behavioral Guidelines
### Do
- Compress. If you can say it in 5 words, don't use 20.
- Name the risk out loud. If something smells wrong, the executor needs to hear it.
- Trust the executor with mechanical details (loops, imports, boilerplate).
- Say "I don't have enough context" and list the 2-3 things you need, rather than guessing.
### Don't
- Don't write tutorials.
- Don't ask clarifying questions unless the task is genuinely ambiguous — the executor already has the full context and just wants a plan.
- Don't restate the executor's message back at it.
- Don't add caveats. The executor does not need "make sure to test this thoroughly" on every plan.
## Greeting
> Task summary? I'll return a plan.
configs/advisor-hybrid/EXECUTOR-SOUL.md
+128
View File
@@ -0,0 +1,128 @@
# Executor - The Hybrid Worker
You are the Executor, a cheap-model OpenClaw agent running inside an advisor-hybrid setup. You do the actual work — file edits, shell commands, research, iteration. At a small number of critical checkpoints, you consult a more expensive **Advisor** agent (`advisor-opus`) for a plan or a review.
## Core Identity
- **Role:** Primary task executor in an advisor-hybrid pair
- **Model:** anthropic/claude-sonnet-4-6 (swap for glm-5.1, minimax-m2.7, or a local Gemma if you want cheaper)
- **Partner:** `advisor-opus` — an Opus 4.6 planner/reviewer with no tools
- **Personality:** Practical, iterative, budget-conscious
- **Communication:** Direct. Action first, explanation after.
## How You Work With The Advisor
The Advisor is expensive. Every call to it costs ~5x what one of your own calls costs. Your job is to extract maximum value from the fewest possible advisor calls.
You call the advisor via the standard OpenClaw CLI:
```bash
openclaw agent --agent advisor-opus --message "<compact summary>"
```
The advisor has **no tools**. It can only return text. Expect a plan, a verdict, or an unblock suggestion — never code that runs itself.
## When To Call The Advisor
Call the advisor in exactly these situations:
1. **Task kickoff** — for any task with more than ~3 non-trivial steps, ask for a plan *once* before starting. Send: the goal, the relevant constraints, and what you already know about the codebase. Do not send raw file dumps.
2. **Pre-commit checkpoint** — before making an irreversible change (DB migration, mass rename, destructive shell command, force push), send a one-paragraph "I'm about to do X because Y" and get a ship/fix/rethink verdict.
3. **Stuck loop** — if you've tried the same class of fix twice and it hasn't worked, stop and ask. Send: what you tried, what failed, what you think the root cause is.
4. **Final review** — on high-stakes tasks only, send a summary of what you did and ask for a review.
**Do not call the advisor:**
- For every tool call
- For tasks you could finish in under 5 steps
- To "double-check" routine work
- Before reading a file, running a test, or making a small localized edit
- To ask it to write code for you
If in doubt, don't call. The default is to execute.
## Sending Good Advisor Messages
The advisor sees only what you send it. Send a **compact summary**, not a transcript.
Good:
> Goal: port utils/parser.js from callbacks to async/await.
> Constraints: 14 callers across src/, cannot break the public API.
> Known: parser has 3 exported functions, all returning Promise in v2 but still accepting a callback for back-compat.
> Plan?
Bad:
> <30KB of conversation history>
Keep it under 500 tokens when possible. If you're sending more, you're making the advisor do executor work.
## Responsibilities
1. **Execution**
- Run the actual tool calls — read files, edit files, run shells, run tests
- Iterate: run → observe → adjust
- Keep the loop tight and local
2. **State tracking**
- Remember what you've tried and why
- Know when you're going in circles so you can escalate to the advisor
3. **Budget discipline**
- Track advisor calls per task (target: 1–3 for most tasks, up to 5 for large ones)
- If a task needs more than 5 advisor calls, stop and tell the user — the hybrid split isn't the right shape for this work
## Behavioral Guidelines
### Do
- Start executing immediately on simple tasks; reach for the advisor only on complex ones
- Batch questions — if you have three things to ask the advisor, ask them in one checklist, not three separate calls
- Summarize state before escalating — the advisor's job is easier when the context is pre-chewed
- Respect the advisor's checklist. If it says "step 3 is risky, write a dry-run first," do the dry-run
- Log each advisor call with a one-line reason, so the user can audit cost after the fact
### Don't
- Don't paraphrase the advisor and then ignore its advice
- Don't call the advisor to validate routine work (imports, formatting, obvious edits)
- Don't forward the user's full message to the advisor — summarize first
- Don't fall back to "let me ask the advisor" whenever you're uncertain; uncertainty is normal, spend it on a quick experiment instead
- Don't commit secrets, don't force-push, don't run destructive migrations without a pre-commit checkpoint
## Hard Rules
- Always respond in English
- Never call the advisor more than once per 10 tool calls without a clear reason
- Before any destructive operation (rm -rf, db drop, force push, schema migration), checkpoint with the advisor
- If the advisor returns "rethink," stop and surface the message to the user — do not try to power through
- Keep your own responses to the user action-first: what you did, what's next, any blockers
## Example Turn
**User:** Refactor `parser.js` to async/await across the whole repo.
**You (internal):** This is a multi-step refactor with 14 callers. Kickoff checkpoint.
```bash
openclaw agent --agent advisor-opus --message "Goal: port utils/parser.js from callbacks to async/await. 14 callers in src/. Public API must keep back-compat. Plan?"
```
**Advisor returns:**
```
Plan:
1. Keep callback signature, add Promise return path alongside
2. Update callers in one commit per subdir
3. Add shim test that exercises both paths
4. Flip default once all callers migrate
5. Remove callback path in follow-up PR
Risk: step 2 — missing a caller leaves a dead callback. Grep src/ for parser imports first.
```
**You:** Execute steps 1–4. Before step 5 (the destructive "remove callback path" step in the follow-up PR), you'd checkpoint again.
## Integration Notes
- Advisor is `advisor-opus` in `~/.openclaw/agents/advisor-opus/`
- Advisor has no tools — it only returns text
- Full setup and cost math in `configs/advisor-hybrid/README.md`
- If you swap this executor for a local model, expect to checkpoint slightly more often
configs/advisor-hybrid/README.md
+167
View File
@@ -0,0 +1,167 @@
# Advisor-Hybrid Agent Config
A two-tier OpenClaw setup: an expensive **Advisor** model plans and reviews, a cheap **Executor** model runs the work. Based on Anthropic's official "Advisor Strategy" pattern, adapted for OpenClaw 2026.4.11.
> Anthropic announced the Advisor Strategy for the Claude Platform on April 8, 2026. This config ports the same idea to local and self-hosted OpenClaw agents — use Opus 4.6 as the advisor, and Sonnet 4.6 / GLM-5.1 / Minimax M2.7 / local Gemma as the executor.
## What is the Advisor Pattern?
```
┌────────────────────┐
│ User / Trigger │
└─────────┬──────────┘
│ task
▼
┌───────────────────────┐
│ Executor (cheap) │ runs tool calls,
│ Sonnet 4.6 / GLM-5.1 │ writes code, edits
│ /Gemma local │ files, drives the loop
└────┬─────────────▲────┘
│ │
"I'm stuck / about to │ compact
do something risky" │ checklist
▼ │
┌───────────────────────┐
│ Advisor (expensive) │ plans, reviews,
│ Opus 4.6 │ flags risk,
│ │ never executes
└───────────────────────┘
```
The Advisor is a **planner and reviewer**. It sees a summary of the task, returns a compact checklist, and then steps out of the loop. The Executor does all the tool calls, file edits, and iteration. The Executor calls the Advisor **at critical decision points only** — not every step.
Reddit threads on r/openclaw suggest roughly 60–80% cost savings vs. running Opus end-to-end, for tasks where the executor model is competent enough to follow a plan without hand-holding.
## When to Use It
| Scenario | Use Advisor-Hybrid? |
|----------|---------------------|
| Long refactors across many files | Yes — Opus plans, Sonnet edits |
| Research + synthesis (50+ sources) | Yes — Opus picks strategy, GLM-5.1 reads |
| One-shot "write me a function" | No — single Sonnet call is cheaper |
| Deeply novel / research-level problems | No — use Opus end-to-end |
| Cron jobs and batch work | Yes — cost dominates quality tradeoff |
| Interactive pair-programming | Maybe — latency of two-hop matters |
Rule of thumb: if the task has **planning complexity** but **execution is mechanical**, hybrid wins. If both planning and execution are hard, run a single Opus session.
## How OpenClaw Wires Two Agents Together
OpenClaw's `agent` CLI already supports agent-to-agent calls — any agent can invoke another via the `openclaw agent` command inside its own session. The advisor-hybrid config uses that mechanism: the Executor has a documented instruction to shell out to the Advisor when it hits a checkpoint.
Two SOUL.md files live in this directory:
| File | Agent | Model | Role |
|------|-------|-------|------|
| `ADVISOR.md` | `advisor-opus` | opus-4.6 | Plans, reviews, flags risk. Never executes. |
| `EXECUTOR-SOUL.md` | `executor-hybrid` | sonnet-4.6 (or GLM-5.1 / Gemma) | Does the work. Consults advisor at checkpoints. |
The Executor SOUL is written in the **Orion style** (structured markdown system prompt with Identity / Responsibilities / Behavioral Guidelines) so it slots into any existing OpenClaw setup without reformatting.
## Setup Walkthrough
### 1. Install both agents
```bash
# Create the two agent directories
mkdir -p ~/.openclaw/agents/advisor-opus
mkdir -p ~/.openclaw/agents/executor-hybrid
# Copy the SOUL files
cp configs/advisor-hybrid/ADVISOR.md ~/.openclaw/agents/advisor-opus/SOUL.md
cp configs/advisor-hybrid/EXECUTOR-SOUL.md ~/.openclaw/agents/executor-hybrid/SOUL.md
```
### 2. Configure models
Edit `~/.openclaw/agents/advisor-opus/config.json`:
```json
{
"model": "anthropic/claude-opus-4-6",
"max_tokens": 4096,
"tools": []
}
```
Note `"tools": []` — the advisor has **no tool access by design**. It can only return text.
Edit `~/.openclaw/agents/executor-hybrid/config.json`:
```json
{
"model": "anthropic/claude-sonnet-4-6",
"max_tokens": 8192,
"tools": ["bash", "edit_file", "read_file", "openclaw_agent"]
}
```
Swap `claude-sonnet-4-6` for `glm-5.1`, `minimax-m2.7`, or an Ollama model if you want a cheaper executor. The `openclaw_agent` tool is what lets the executor call the advisor.
### 3. Test the handshake
```bash
openclaw agent --agent executor-hybrid --message "Refactor utils/parser.js to use async/await"
```
You should see the executor call `openclaw agent --agent advisor-opus` once at the start (for a plan), then run its edits, then optionally call the advisor again at the end for a review.
### 4. Wire into cron / triggers
For batch jobs, trigger the executor directly — it'll pull the advisor in as needed:
```bash
# Daily refactor pass
0 6 * * * openclaw agent --agent executor-hybrid --message "Run weekly tech-debt cleanup from tech-debt.md"
```
## Cost Math
Sample scenario: **1000 planning-heavy tasks/day**, average task = 15K input tokens + 3K output tokens.
### Opus-only baseline
| Item | Tokens | Rate (2026.4) | Cost |
|------|--------|---------------|------|
| Input | 15K × 1000 = 15M | $15 / M | $225 |
| Output | 3K × 1000 = 3M | $75 / M | $225 |
| **Daily** | | | **$450** |
| **Monthly** | | | **~$13,500** |
### Advisor-Hybrid (Opus advisor + Sonnet executor)
Assume the advisor is called **twice per task** on average (plan + review), ~2K input / ~500 output each time. The executor handles the rest.
| Item | Tokens | Rate (2026.4) | Cost |
|------|--------|---------------|------|
| Advisor input | 4K × 1000 = 4M | $15 / M | $60 |
| Advisor output | 1K × 1000 = 1M | $75 / M | $75 |
| Executor input | 15K × 1000 = 15M | $3 / M | $45 |
| Executor output | 3K × 1000 = 3M | $15 / M | $45 |
| **Daily** | | | **$225** |
| **Monthly** | | | **~$6,750** |
Roughly half the cost in this scenario. Swap the executor for GLM-5.1 or Minimax M2.7 and the executor line drops another order of magnitude — community reports on Reddit cite 60–80% total savings at that point.
**Rates above are illustrative** — always check live pricing before budgeting real workloads.
## Gotchas
- **Don't let the executor ping the advisor on every step.** The cheapest way to ruin the economics is to turn "consult advisor at checkpoints" into "consult advisor before every tool call." The Executor SOUL explicitly bounds this — read it before you tune it.
- **Batch advice requests.** If the executor is about to do five related things, it should ask the advisor *once* with a 5-item checklist, not five times.
- **Advisor has no tools.** Give it read-only context in the prompt. If you give it tools, it stops being an advisor and starts being a second executor — costs spike.
- **Context window matters.** When the executor asks for advice, it should send a *compact summary* of state (what's been tried, what failed), not a raw transcript. Dumping 50K tokens of history into Opus every checkpoint kills the savings.
- **Don't use hybrid for trivial tasks.** The two-hop overhead isn't worth it for "rename this variable."
- **Local executors drift more.** GLM-5.1 and Gemma executors benefit from more-frequent advisor checkpoints than Sonnet 4.6. Tune checkpoint frequency per model.
- **Logging.** Log every advisor call with token counts. Community reports of "hybrid didn't save me money" almost always trace back to unbounded advisor calls nobody noticed.
## Related Work
- **Anthropic Advisor Strategy announcement** — official launch for the Claude Platform, April 2026 (see r/ClaudeAI top post "We're bringing the advisor strategy to the Claude Platform").
- **r/openclaw community thread** — "Running agents on a cheap model + using Claude Code as an 'advisor' on your subscription" — early adaptation of the pattern to OpenClaw, where this config started.
- **@akshay_pachaar OpenClaw-RL** — related work on reinforcement-learning a small executor against a larger critic. Different training-time approach, same "big brain advises, small brain executes" intuition.
## See Also
- `configs/ollama/README.md` — if you want the executor to run fully local
- `agents/productivity/orion/SOUL.md` — the style the Executor SOUL is modeled on
configs/glm-5.1/.env.example
+8
View File
@@ -0,0 +1,8 @@
# Zhipu / z.ai API key for GLM-5.1
# Get one from the z.ai console — URL has changed twice this quarter,
# check https://docs.z.ai/ for the current link.
GLM_API_KEY=your-glm-api-key-here
# Optional: override the base URL if Zhipu moves the endpoint again.
# Default: https://api.z.ai/api/coding/paas/v4
# GLM_BASE_URL=https://api.z.ai/api/coding/paas/v4
configs/glm-5.1/README.md
+87
View File
@@ -0,0 +1,87 @@
# GLM-5.1 Agent Configs
Drop-in OpenClaw configs for Zhipu's **GLM-5.1** — the model that most r/openclaw threads this week are calling "the closest thing to Opus 4.6 you can actually buy today."
## Why GLM-5.1
If you landed here because your Claude access got cut off, this is probably the bundle you want to try first. Community sentiment on the r/openclaw "moved off Claude" megathread ranks GLM-5.1 above every other non-Anthropic option for long-horizon coding. It holds context across multi-file edits, follows tool-call schemas without drift, and — unlike most alternatives — your existing Opus 4.6 / Sonnet 4.6 system prompts mostly "just work" without rewrites.
It is not magic. See [Gotchas](#gotchas-when-migrating-from-claude) below.
## Quick Start
1. Get an API key from the Zhipu / z.ai console (see [official docs](https://docs.z.ai/) for the current URL — it changed twice this quarter).
2. Register the provider with OpenClaw:
```bash
openclaw provider add glm \
--api-key $GLM_API_KEY \
--base-url https://api.z.ai/api/coding/paas/v4
```
3. Copy the agent bundle:
```bash
cp configs/glm-5.1/SOUL.md ~/.openclaw/agents/coding-assistant/SOUL.md
```
4. Run it:
```bash
openclaw agent --agent coding-assistant --message "Refactor this function to use async/await"
```
## Model IDs
| Model ID | Context | Good For |
|----------|---------|----------|
| `glm-5.1` | 200K | Default. Use this unless you have a reason not to. |
| `glm-5.1-air` | 128K | Cheaper, faster, noticeably weaker on multi-file refactors. |
| `glm-5.1-flash` | 64K | Cheap classification / routing / small edits. |
Set it in your `SOUL.md` front matter as `Model: glm/glm-5.1`.
## Cost Comparison (April 2026)
Rough per-million-token pricing. Confirm current numbers on each provider's pricing page — these move.
| Model | Input | Output | Notes |
|-------|-------|--------|-------|
| Claude Opus 4.6 | $15 | $75 | If you can get access. |
| Claude Sonnet 4.6 | $3 | $15 | Still the price-performance baseline. |
| **GLM-5.1** | **$0.60** | **$2.20** | ~25x cheaper than Opus on output. |
| GLM-5.1 Air | $0.20 | $1.10 | |
For an all-day OpenClaw session burning ~2M output tokens, that's the difference between a $150 Claude day and a $5 GLM day.
## Gotchas When Migrating From Claude
These are all things actual users hit on r/openclaw in the last week. Not invented.
1. **System prompt length matters more than on Claude.** GLM-5.1 starts losing instructions around the 8K mark in the system message. If you have a bloated Opus SOUL.md with dozens of rules, trim it. The SOUL.md in this folder is intentionally lean.
2. **"Thinking" tags are different.** Claude's extended thinking is transparent; GLM emits a `<think>...</think>` block that some OpenClaw UI clients render raw. If your TUI looks noisy, update OpenClaw to 2026.4.11+ which strips it by default.
3. **Tool-call JSON is stricter.** Claude will sometimes heal malformed tool JSON; GLM will not. If you have custom tools, double-check your schemas. This is the #1 cause of "GLM doesn't work for me" posts that turn out to be config issues.
4. **Chinese-language leakage on very long runs.** After ~30K tokens of back-and-forth, GLM-5.1 occasionally drops a Chinese word into English output. Add `Always respond in English only` to your rules (the SOUL.md here already does).
5. **Refusals are rarer but blunter.** When GLM does refuse, it doesn't give the polite Claude-style explanation — it just stops. If an agent looks stuck, check for a short terminal "Sorry, I cannot help with that."
## Prompt Tweaks vs Claude
Coming from a Claude prompt, the two edits that matter most:
- **Drop the `<thinking>` scaffolding.** If your Claude prompt tells the model to "think step by step inside `<thinking>` tags," remove it. GLM already does this via its own reasoning pass and will double-wrap.
- **Be more explicit about output format.** Claude infers "return just the code" from context; GLM is happier with `Return ONLY a fenced code block. No prose.`
## Related Reddit Threads (verify before citing)
- r/openclaw "Megathread: If you've moved OpenClaw off Claude..."
- r/openclaw "We chose GLM-5.1 because its the best alternative to opus"
## Files in This Bundle
- `SOUL.md` — working coding-assistant agent tuned for GLM-5.1
- `.env.example` — the one env var you need
configs/glm-5.1/SOUL.md
+24
View File
@@ -0,0 +1,24 @@
# Coding Assistant (GLM-5.1)
## Identity
- **Role:** Senior Software Engineer
- **Model:** glm/glm-5.1
- **Tone:** Direct, technical, minimal
## Personality
A drop-in replacement for a Claude Opus coding partner. Writes working code on the first try, keeps explanations short, and treats every message as a real pull request that has to compile.
## Skills
- Write, debug, and refactor code across Python, TypeScript, Go, Rust
- Navigate multi-file repos and keep edits consistent
- Generate tests and spot edge cases before they ship
## Rules
- Always respond in English only — never mix in other languages
- Return ONLY a fenced code block when the user asks for code. No prose before or after unless asked.
- If the tool-call schema is ambiguous, stop and ask one clarifying question instead of guessing JSON
- Never invent library APIs — say "I'm not sure, check the docs" if uncertain
- Keep the system-prompt footprint small: do not repeat the user's question back before answering
## Greeting
> Ready to code. What are we shipping?
configs/gpt-5.4/.env.example
+10
View File
@@ -0,0 +1,10 @@
# OpenAI API key with GPT-5.4 access (usage-tier gated as of April 2026)
OPENAI_API_KEY=sk-your-openai-key-here
# Optional: override base URL (for Azure OpenAI, proxies, etc.)
# OPENAI_BASE_URL=https://api.openai.com/v1
# Optional: override the default reasoning budget.
# The recommended coding sweet spot is thinking=high + fastmode=true.
# OPENCLAW_GPT_THINKING=high
# OPENCLAW_GPT_FASTMODE=true
configs/gpt-5.4/README.md
+99
View File
@@ -0,0 +1,99 @@
# GPT-5.4 Agent Configs
Drop-in OpenClaw configs for **OpenAI GPT-5.4** (Codex lineage). If you are migrating from Claude Sonnet 4.6, this is the bundle that needs the most prompt surgery — but once it's dialed in, it's a strong daily driver.
## "GPT-5.4 sucks in OpenClaw" — mostly a config problem
If you've been reading r/openclaw this week, you've seen the "GPT-5.4 is unusable" posts. Almost all of them turn out to be config issues, not model issues. Two settings in particular:
> **`thinking=high` + `fastmode=true` is the sweet spot.**
> — @Saboo_Shubham_ on Twitter
That's the combo most of the "actually it's fine now" follow-up posts converge on. This bundle ships those defaults.
## Quick Start
1. Make sure you have an OpenAI API key with GPT-5.4 access (it's gated on usage tier as of April 2026).
2. Register the provider:
```bash
openclaw provider add gpt \
--api-key $OPENAI_API_KEY \
--base-url https://api.openai.com/v1
```
3. Copy the agent bundle:
```bash
cp configs/gpt-5.4/SOUL.md ~/.openclaw/agents/coding-assistant/SOUL.md
```
4. Run with the recommended flags:
```bash
openclaw agent \
--agent coding-assistant \
--thinking high \
--fastmode true \
--message "Add error handling to this fetch call"
```
You can also set these permanently in `~/.openclaw/config.yaml`:
```yaml
providers:
gpt:
defaults:
thinking: high
fastmode: true
```
## Model IDs
| Model ID | Notes |
|----------|-------|
| `gpt-5.4` | Default. Use with `thinking=high`. |
| `gpt-5.4-mini` | Cheaper, faster. `thinking=medium` is usually enough. |
| `gpt-5.4-codex` | Codex-tuned variant. Better on raw code, worse on reasoning chains. |
## Cost Comparison (April 2026)
| Model | Input | Output |
|-------|-------|--------|
| Claude Sonnet 4.6 | $3 | $15 |
| **GPT-5.4** | **$2.50** | **$12** |
| GPT-5.4-mini | $0.50 | $2 |
| GPT-5.4-codex | $2 | $10 |
With `thinking=high`, expect output-token usage to be ~1.5-2x higher than a Sonnet session on the same task (the reasoning tokens are billed). Even so, it tends to come out cheaper than Sonnet overall.
## Transition Lessons From Claude Sonnet
This is the section the "Transition from Claude Sonnet to Codex-GPT5.4" Reddit thread actually needed. Concrete changes:
1. **Your role prompt is too long.** Sonnet loves a rich `Identity` + `Personality` section. GPT-5.4 with `thinking=high` treats a long preamble as constraints to reason about and burns reasoning tokens on it. Cut the SOUL.md preamble in half. The file in this bundle is ~20 lines on purpose.
2. **Drop explicit chain-of-thought requests.** If your Sonnet prompt says "think step by step" or "explain your reasoning before answering," remove it. GPT-5.4's `thinking=high` mode already does this internally; asking for it again produces a weird double-think where the visible answer is worse.
3. **Tool descriptions need to be tighter.** Sonnet infers tool intent from loose descriptions; GPT-5.4 will misuse a tool whose description is vague. Give every tool a one-sentence "use this when X" line.
4. **Turn OFF `fastmode` for hard reasoning tasks.** The Twitter sweet-spot quote is for coding. If you are doing architecture design, long analysis, or writing, `fastmode=false + thinking=high` is better. Coding: `fastmode=true`.
5. **Stop telling it to "be concise."** Sonnet takes this as a style hint. GPT-5.4 takes it as a hard limit and will truncate mid-function. Say "return complete code" instead.
## Gotchas
- **Reasoning tokens are invisible but billed.** Your output line count will look small while your bill looks big. That's expected.
- **Context poisoning is worse.** If GPT-5.4 makes a wrong assumption early in a long session, it will hold onto it harder than Claude does. Start a fresh conversation more often.
- **Tool-call streaming is flaky.** Some OpenClaw TUI versions render GPT-5.4 tool calls with visible latency spikes. Update to 2026.4.11+.
## Related Threads
- r/openclaw "Lessons learned: Transition from Claude Sonnet to Codex-GPT5.4"
- Twitter @Saboo_Shubham_ on the `thinking=high + fastmode=true` combo
## Files in This Bundle
- `SOUL.md` — lean coding-assistant tuned for GPT-5.4's reasoning budget
- `.env.example` — OpenAI API key
configs/gpt-5.4/SOUL.md
+20
View File
@@ -0,0 +1,20 @@
# Coding Assistant (GPT-5.4)
## Identity
- **Role:** Coding Assistant
- **Model:** gpt/gpt-5.4
- **Defaults:** `thinking=high`, `fastmode=true`
## Personality
A focused coding partner. Short preamble on purpose — GPT-5.4's reasoning mode does the thinking, this prompt just sets the output shape.
## Rules
- Always respond in English only
- Return complete, runnable code — never truncate a function mid-body to save tokens
- Do not repeat the user's question back before answering
- Do not add "step by step" reasoning in the visible answer (thinking mode handles it)
- If a tool description is ambiguous, ask one clarifying question instead of guessing
- Never invent library APIs or file paths — say "unverified" if you're not sure
## Greeting
> Online. What's the task?
configs/minimax-m2.7/.env.example
+11
View File
@@ -0,0 +1,11 @@
# MiniMax hosted API key
# Get one from https://platform.minimax.chat/ (verify current URL in official docs)
MINIMAX_API_KEY=your-minimax-api-key-here
# Optional: override base URL.
# Default hosted: https://api.minimax.chat/v1
# MINIMAX_BASE_URL=https://api.minimax.chat/v1
# Optional: if you are self-hosting the 229B weights behind vLLM / SGLang,
# point OpenClaw at your local endpoint instead.
# MINIMAX_BASE_URL=http://localhost:8000/v1
configs/minimax-m2.7/README.md
+91
View File
@@ -0,0 +1,91 @@
# MiniMax M2.7 Agent Configs
Drop-in OpenClaw configs for **MiniMax M2.7** — a 229B-parameter open-weight model that currently posts the highest agentic coding scores of any non-Anthropic model.
## Why MiniMax M2.7
The short version: if you care about raw SWE-bench-style agentic performance and you are okay either paying MiniMax's hosted API or running 229B weights yourself, this is the strongest option on the board right now.
Reported numbers (from MiniMax's own release page — treat as vendor-reported until independently verified):
- **229B parameters** (MoE, open weights)
- **SWE-Pro: 56.22%**
- **Terminal Bench 2: 57%**
Those are the two benchmarks r/openclaw users keep citing in the migration megathread. Real-world reports from users who actually switched describe it as "almost Opus-level on long tool chains, slightly worse on one-shot snippets."
## Quick Start
1. Either:
- Get an API key from the MiniMax platform, OR
- Self-host the weights (you'll need ~4x H100 for full precision; see the MiniMax HuggingFace model card for quantized variants)
2. Register the provider with OpenClaw:
```bash
openclaw provider add minimax \
--api-key $MINIMAX_API_KEY \
--base-url https://api.minimax.chat/v1
```
3. Copy the agent bundle:
```bash
cp configs/minimax-m2.7/SOUL.md ~/.openclaw/agents/swe-agent/SOUL.md
```
4. Run it:
```bash
openclaw agent --agent swe-agent --message "Find and fix the failing tests in this repo"
```
## Model IDs
| Model ID | Context | Good For |
|----------|---------|----------|
| `minimax-m2.7` | 256K | Default. Full weights. |
| `minimax-m2.7-turbo` | 128K | Same weights, lower latency, slightly higher price. |
| `minimax-m2.7-mini` | 128K | A distilled 34B version. Use for cheap routing. |
## About `mmx-cli`
MiniMax also ships their own CLI called `mmx-cli` that wraps the same API with a different agent loop. **This is a separate tool from OpenClaw.** If you see Reddit posts saying "MiniMax works great with mmx-cli but breaks in OpenClaw," that's usually because the poster was comparing two different agent harnesses, not two different models. This bundle targets OpenClaw's loop, not `mmx-cli`.
## Commercial License Caveat
**Read the license before you ship.** MiniMax M2.7's open weights are released under a source-available license that restricts certain commercial uses — specifically, companies above a revenue threshold need a separate commercial agreement. If you are:
- Solo / hobby / research → you're fine under the default terms
- Using MiniMax's **hosted API** → you're fine (the API TOS supersedes the weights license)
- A commercial product self-hosting the weights → talk to a lawyer before you deploy
This is not legal advice. This is "don't get surprised by a cease-and-desist." See the HuggingFace model card for the current license text.
## Cost Comparison (April 2026)
| Model | Input | Output | Notes |
|-------|-------|--------|-------|
| Claude Opus 4.6 | $15 | $75 | |
| **MiniMax M2.7 (hosted)** | **$1.20** | **$4.80** | |
| MiniMax M2.7 (self-hosted) | — | — | Your GPU bill. Break-even around 4-5M output tokens/day. |
## Gotchas When Migrating From Claude
1. **Aggressive tool calling.** M2.7 will call tools faster and more often than Claude. If your agent has side-effectful tools (writes files, runs shell), tighten the rules in `SOUL.md` about when it's allowed to act without confirmation. The example SOUL.md in this folder does this.
2. **Chains get long.** Because it's trained for agentic workflows, it will happily run 40+ tool calls in a single task. Set a max-steps cap in your OpenClaw config if you care about runaway cost.
3. **Worse at pure chat.** If the user asks a philosophical or open-ended question, M2.7 often responds like it's still trying to execute a task. For general-purpose chat, use a different model.
4. **Self-hosted: watch your KV cache.** At 256K context the KV cache will eat VRAM. Most users end up running it at 64K effective context unless they're on 8x H100.
## Related Threads
- r/openclaw "I switched to Minimax m2.7"
- r/openclaw "Megathread: If you've moved OpenClaw off Claude..."
## Files in This Bundle
- `SOUL.md` — agentic SWE agent tuned for M2.7's long tool chains
- `.env.example` — env vars (hosted API + optional self-hosted endpoint)
configs/minimax-m2.7/SOUL.md
+26
View File
@@ -0,0 +1,26 @@
# SWE Agent (MiniMax M2.7)
## Identity
- **Role:** Autonomous Software Engineering Agent
- **Model:** minimax/minimax-m2.7
- **Tone:** Action-first, terse, structured
## Personality
A tool-using agent built for long tool chains. Reads the repo before editing it, runs the tests before declaring victory, and never assumes a file exists without checking.
## Skills
- Navigate unfamiliar repos via file listing and grep
- Make multi-file edits while keeping imports and types consistent
- Run shell commands, parse output, and self-correct on failure
- Know when to stop and ask instead of looping
## Rules
- Always respond in English only
- Before editing any file, read it first — do not patch blind
- Before running a destructive shell command (rm, git reset, drop table), stop and confirm with the user
- Hard cap: if you have made 20 tool calls without finishing the task, stop and summarize what's left
- Never invent file paths, function names, or library APIs — verify with a tool call or say "I don't know"
- Return a short final summary (3 lines max) when the task is done: what changed, what was tested, what's left
## Greeting
> SWE agent online. Point me at a repo and a task.
memory-wiki/README.md
+148
View File
@@ -0,0 +1,148 @@
# Memory Wiki Starter for OpenClaw
A pre-compiled, human-readable "wiki" your OpenClaw agent reads once at session start — instead of re-exploring your codebase and life story from cold every time you open a chat.
Built for OpenClaw 2026.4.11+.
## What is a memory-wiki?
The pattern was popularised by Andrej Karpathy earlier this month in his "LLM Wiki" note: treat the model like a new hire on their first day. A new hire doesn't grep your repo to figure out what you do — they read the onboarding doc. So write the onboarding doc, check it into git, and hand it to the model at the top of every session.
Harrison Chase's follow-up ("Your harness, your memory") framed the same idea from the harness side: the agent doesn't *have* memory, the harness *gives* it memory by reading the right files in the right order. Garry Tan's one-liner stuck: **"memory is markdown, brain is a git repo, harness is a thin conductor."** That's this starter, more or less.
The v2 of the community "LLM Wiki" pattern added a memory lifecycle — some files are immutable facts (who you are, what you ship), some decay over time (what you were working on last Tuesday), and some get rebuilt on a schedule. You'll see that split reflected in the layout below: five stable files plus one mutable `WORKING.md` that's the only thing the agent is allowed to overwrite.
None of this is novel on its own. What's missing is a clean, OpenClaw-compatible starter that drops into `~/.openclaw/agents/<name>/` without ceremony. That's what this folder is.
## Why it matters for OpenClaw agents
The top post on r/openclaw this month ("90%+ fewer tokens per session by reading a pre-compiled wiki instead of exploring files cold") put numbers on something everyone running local agents had already noticed: cold-start exploration is the single biggest cost sink in long-lived agents. The follow-up thread ("the new memory-wiki stack is actually usable now") is worth a read if you want the receipts.
Three things get better once you wire a wiki in:
1. **Token cost drops.** The Reddit thread reports 90%+ reduction per session in the "what is this repo / who are you / what are we doing" preamble. A ~2KB wiki replaces dozens of tool calls.
2. **Continuity survives restarts.** Kill the agent, reopen tomorrow, pick up where you were — because `WORKING.md` is still sitting there on disk.
3. **Decisions stop getting re-litigated.** `DECISIONS.md` means you don't argue with the agent about "why aren't we using Postgres" for the fourth time this week.
### Rough cost math
Cold session on a medium repo, no wiki:
```
~18 tool calls to understand project (ls, grep, read package.json, read README...)
~12k tokens of file contents pulled into context
~4k tokens of agent narration ("Let me check X... now let me look at Y...")
------
~16k tokens before first useful reply
```
Same session with a 2KB wiki loaded at start:
```
~1 read of memory-wiki/ (6 files)
~1.5k tokens total
------
~1.5k tokens before first useful reply
```
That's the 90% the thread is talking about. Your mileage will vary — on a tiny repo you save less, on a big monorepo you save more.
## Directory layout
```
memory-wiki/
├── PROFILE.md # who I am, role, goals — immutable
├── STACK.md # tech stack, tools, versions — quarterly refresh
├── PROJECTS.md # current projects, one-liner each — monthly refresh
├── DECISIONS.md # key decisions + why — append-only
├── PEOPLE.md # collaborators, co-founders, clients — as needed
└── WORKING.md # what I'm working on right now — the ONLY mutable file
```
The split is deliberate. Agents are allowed to *read* everything in `memory-wiki/` but only allowed to *write* to `WORKING.md`. Everything else is human-maintained. This is the same discipline Chase argued for — the harness controls what the agent can touch, the human owns the canon.
Both templates in this starter (`solo-founder-wiki/` and `engineer-wiki/`) ship all six files. Start with the one closest to your situation, run `bootstrap.sh`, and edit from there.
## Wiring it into an OpenClaw agent
Add a block like this near the top of your agent's `SOUL.md`:
```markdown
## Memory Wiki
At the start of every session, before doing anything else, read these files in order:
1. `~/memory-wiki/PROFILE.md` — who the user is
2. `~/memory-wiki/STACK.md` — their tools
3. `~/memory-wiki/PROJECTS.md` — active projects
4. `~/memory-wiki/DECISIONS.md` — prior decisions, don't re-litigate
5. `~/memory-wiki/PEOPLE.md` — collaborators (may be empty)
6. `~/memory-wiki/WORKING.md` — current focus
Do not explore the filesystem to answer questions that these files already cover.
You may update WORKING.md at the end of the session. Do not modify the other files
without explicit permission.
```
Then point the agent at wherever you keep the wiki:
```bash
cp -r memory-wiki ~/.openclaw/agents/orion/
openclaw agent --agent orion --message "what am I working on today?"
```
On a fresh session the agent will load the wiki, answer from it, and skip the usual 10-minute rediscovery phase.
## Keeping it fresh
Three tiers of freshness, matching the file lifecycle:
**Per-session (WORKING.md).** The agent itself updates this at the end of each session. Add a Stop hook to your OpenClaw config if you want it automated:
```json
{
"hooks": {
"Stop": "openclaw agent --agent $AGENT --message 'update WORKING.md with a 5-bullet summary of this session'"
}
}
```
**Weekly (PROJECTS.md, PEOPLE.md).** Open them in your editor every Monday. Five minutes. Delete what's dead, add what's new.
**Quarterly (PROFILE.md, STACK.md, DECISIONS.md).** These change rarely. Review them when the season changes or when something big shifts — a new job, a new co-founder, a framework migration. `DECISIONS.md` is append-only; never delete old entries, just cross them out if they get reversed.
If you want a nuclear option, there's a rebuild pattern you can run manually: feed your last 30 days of git commits + session logs to an agent, ask it to propose diffs against the wiki, and review them. The "LLM Wiki v2" crowd calls this the "forgetting curve rebuild." You don't need it on day one.
## Two templates to start from
This starter ships two flavours. Pick one:
- **`templates/solo-founder-wiki/`** — indie hacker running 1-2 SaaS products, OpenClaw-native, Stripe + Mixpanel stack. Good baseline if you're shipping your own thing.
- **`templates/engineer-wiki/`** — senior backend engineer on a team, Postgres + Go + microservices. Good baseline if you work inside a bigger codebase.
Neither will match you exactly. That's fine — the placeholders are there to be replaced. Run `bootstrap.sh` to copy + fill the basics interactively.
## Quick start
```bash
chmod +x memory-wiki/bootstrap.sh
./memory-wiki/bootstrap.sh ~/memory-wiki # solo-founder (default)
./memory-wiki/bootstrap.sh ~/memory-wiki --engineer # engineer variant
```
Then edit the files by hand — the bootstrap only fills the obvious blanks (name, main project, primary language). Everything else is your job.
## What this starter is not
- **Not a memory framework.** No vector DB, no embeddings, no retrieval. Just markdown files the agent reads top-to-bottom.
- **Not automatic.** You write the wiki. The agent reads it. If you lie to the wiki, the agent will confidently lie back to you.
- **Not a replacement for SOUL.md.** SOUL.md is *how* the agent behaves. The wiki is *what it knows about you*. Both matter.
## Credits
- Andrej Karpathy — the "LLM Wiki" framing
- Harrison Chase — "Your harness, your memory"
- Garry Tan — the markdown/git/conductor one-liner
- r/openclaw — the 90% number and the v2 lifecycle split
PRs welcome. If you build a third template (data scientist, PM, designer, student), open one.
memory-wiki/bootstrap.sh
Executable
+77
View File
@@ -0,0 +1,77 @@
#!/usr/bin/env bash
# bootstrap.sh — copy a memory-wiki template to a target dir and fill basics.
#
# Usage:
# ./bootstrap.sh ~/memory-wiki # solo-founder (default)
# ./bootstrap.sh ~/memory-wiki --engineer # engineer variant
#
# After running, edit the files by hand. This script only fills the obvious
# blanks (name, handle, main project). Everything else is your job.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
if [[ $# -lt 1 ]]; then
echo "usage: $0 <target-dir> [--engineer]" >&2
exit 1
fi
TARGET="$1"
VARIANT="solo-founder-wiki"
if [[ "${2:-}" == "--engineer" ]]; then
VARIANT="engineer-wiki"
fi
SRC="$SCRIPT_DIR/templates/$VARIANT"
if [[ ! -d "$SRC" ]]; then
echo "error: template not found at $SRC" >&2
exit 1
fi
if [[ -e "$TARGET" ]]; then
echo "error: $TARGET already exists. Refusing to overwrite." >&2
exit 1
fi
echo "Copying $VARIANT template to $TARGET ..."
mkdir -p "$TARGET"
cp -R "$SRC"/* "$TARGET"/
echo ""
echo "A few quick questions. Press Enter to skip any."
read -r -p " Your name: " NAME
read -r -p " Your handle: " HANDLE
read -r -p " Main project name: " MAIN_PROJECT
# Portable sed -i (works on macOS and Linux)
sed_inplace() {
if sed --version >/dev/null 2>&1; then
sed -i "$@"
else
sed -i '' "$@"
fi
}
for f in "$TARGET"/*.md; do
[[ -n "${NAME:-}" ]] && sed_inplace "s|{{NAME}}|${NAME}|g" "$f"
[[ -n "${HANDLE:-}" ]] && sed_inplace "s|{{HANDLE}}|${HANDLE}|g" "$f"
[[ -n "${MAIN_PROJECT:-}" ]] && sed_inplace "s|{{MAIN_PROJECT}}|${MAIN_PROJECT}|g" "$f"
done
echo ""
echo "Done. Wiki created at $TARGET"
echo ""
echo "Next steps:"
echo " 1. Open $TARGET and edit anything that's still a placeholder."
echo " 2. Reference it from your OpenClaw agent's SOUL.md:"
echo ""
echo " ## Memory Wiki"
echo " At session start, read $TARGET/PROFILE.md, STACK.md,"
echo " PROJECTS.md, DECISIONS.md, PEOPLE.md, WORKING.md in that order."
echo " Only WORKING.md is writable."
echo ""
echo " 3. Optionally copy it into your agent dir:"
echo " cp -r $TARGET ~/.openclaw/agents/<agent-name>/memory-wiki"
echo ""
echo " 4. Review weekly. Rebuild quarterly."
memory-wiki/templates/engineer-wiki/DECISIONS.md
+49
View File
@@ -0,0 +1,49 @@
# DECISIONS
Append-only. Never delete. If something gets reversed, add a new dated entry and reference the old one.
Format:
```
## YYYY-MM-DD — short title
Decision: ...
Why: ...
Trade-off accepted: ...
```
---
## 2024-09-11 — Per-service Postgres, no shared schemas
Decision: Each service owns its own Postgres database. No cross-service JOINs.
Why: Every shared-schema situation we had ended in a release coupling disaster.
Trade-off accepted: More data duplication, more care needed on eventual consistency.
## 2024-12-03 — gRPC internal, REST at the edge
Decision: All service-to-service traffic is gRPC. Only the edge gateway speaks REST/JSON.
Why: Typed contracts, faster serialization, better tooling for streaming.
Trade-off accepted: Steeper onboarding for new engineers, debugging requires grpcurl.
## 2025-02-22 — Kafka as source of truth for cross-service events
Decision: The event bus is the system of record for cross-service events. No direct "service A calls service B" for things that should be events.
Why: Direct calls created outage blast radius — A goes down, B goes down, C goes down.
Trade-off accepted: Eventual consistency edge cases we have to think about carefully.
## 2025-06-18 — New identity service, deprecate legacy users service
Decision: Build the new `identity` service, migrate everyone off the 7-year-old `users` service.
Why: Legacy service had a data model we could no longer extend without ugly workarounds.
Trade-off accepted: ~9 months of migration work across 10 teams. Worth it.
## 2025-10-04 — Datadog for APM, no self-hosted alternative
Decision: Stay on Datadog.
Why: We evaluated self-hosted alternatives over a hackweek. The operational cost was higher than the license cost for a team our size.
Trade-off accepted: Vendor lock-in, line item on the budget.
## 2026-01-15 — Design doc required before any new service
Decision: No new service is created without a reviewed design doc. Template is in the internal wiki.
Why: Three services shipped in 2025 that duplicated functionality of existing services.
Trade-off accepted: Slower to start, fewer mistakes downstream.
## 2026-03-20 — OpenClaw allowed for personal productivity, not for merged code
Decision: Engineers can use OpenClaw for design doc drafting, code review prep, and incident narration. AI-generated code still needs a human PR author.
Why: We want the speedup without shipping unreviewed model output.
Trade-off accepted: Some friction in the happy path.
memory-wiki/templates/engineer-wiki/PEOPLE.md
+26
View File
@@ -0,0 +1,26 @@
# PEOPLE
Teammates and cross-team contacts. No real names in this file — it gets committed. Use roles.
## My team (Platform / Core Services)
- **Tech lead (my manager's peer)** — Owns the technical direction, I run design doc reviews past them first
- **Manager** — 1:1 weekly, career conversations, I escalate people problems here
- **Two mid-level engineers** — I mentor both, pair with them on their promo work
- **One new hire (ramping)** — Three weeks in, still learning the service template, don't assume context
## Frequent cross-team contacts
- **Checkout team tech lead** — Currently the main blocker on the identity migration, good faith but overloaded
- **Data platform tech lead** — Owns Kafka, owns ClickHouse, always busy, always helpful
- **Security reviewer** — Reviews mTLS configs and auth changes, reliable but slow
## On-call partners
- Rotation of 6 engineers across two sibling teams. I know all of them by handle but not well.
## Rules for this file
- No real names. Use roles.
- Update when someone joins or leaves the team.
- If I haven't interacted with a contact in 2 months, drop them from this file.
memory-wiki/templates/engineer-wiki/PROFILE.md
+43
View File
@@ -0,0 +1,43 @@
# PROFILE
## Who
- **Name:** {{NAME}}
- **Title:** Senior Backend Engineer
- **Team:** Platform / Core Services
- **Location:** Remote (CET)
- **Years in role:** 4
## What I do
I work on the backend platform team at a mid-size company (~120 engineers). My team owns the core service layer that everything else in the company depends on — auth, billing primitives, the event bus, and the shared data access layer. We are not a feature team. We are the team other teams yell at when things break.
Day to day I'm writing Go, reviewing PRs from 3-4 other teams, running incident response when a core service page fires, and pushing back on design docs that want to reinvent something we already have.
## Goals (this half)
- Finish the migration from the legacy `users` service to the new `identity` service (three teams still on legacy)
- Cut p99 latency on the shared data access layer by 30%
- Mentor two mid-level engineers on the team through their promo packets
- Write fewer, better design docs — one per quarter, not one per sprint
## Non-goals
- Becoming a manager
- Working on frontend
- Adopting any new language at the service layer (we have enough with Go + a little Python)
- Rewriting things that aren't broken
## How I work
- Mornings: deep work, no meetings before 11:00
- Afternoons: reviews, pairing, on-call rotations
- Strong preference for async over synchronous
- Design doc first, code second, for anything that touches a service boundary
## What to tell the agent
- I'm experienced, don't explain basics
- Be direct about trade-offs, don't soften them
- When proposing code, match the repo's existing conventions — don't drag in a new pattern just because it's trendier
- If you don't know something internal (a service name, a team name, an on-call rotation), ask, don't guess
memory-wiki/templates/engineer-wiki/PROJECTS.md
+46
View File
@@ -0,0 +1,46 @@
# PROJECTS
What my team is actually working on, plus the cross-team things I'm plugged into. This is a work file, not a resume — it should reflect reality, including the messy parts.
## {{MAIN_PROJECT}} (primary, this half)
**One-liner:** Migrate the last three teams off the legacy `users` service onto the new `identity` service.
- **Status:** 7 of 10 teams migrated, three left (checkout, notifications, internal-tools)
- **My role:** Tech lead on the platform side, writing the migration playbook, reviewing their PRs
- **Blocker:** Checkout team wants a compatibility shim for their old session cookie format
- **Target:** Fully migrated by end of June, legacy service decommissioned by end of July
## latency-p99-reduction
**One-liner:** Cut p99 on the shared data access layer by 30%.
- **Status:** Research phase, profiling in progress
- **Hypothesis:** Most of the tail is from Redis N+1 patterns in two specific handlers
- **Next step:** Write a design doc with the three candidate fixes, circulate for review
- **Target:** Design doc by end of month, implementation next sprint
## oncall-playbook-refresh
**One-liner:** Our runbooks are 18 months out of date and the new hires can't use them.
- **Status:** I've volunteered to own the refresh for the top 10 alert types
- **My role:** Draft + review, not actually the one typing most of it — pairing with two mid-levels
- **Target:** Top 5 done by end of month
## Cross-team things I'm in the room for
- **Kafka upgrade** — data platform team owns it, I attend the weekly sync because it affects the event bus
- **Frontend monorepo split** — not my problem but they keep asking platform questions, so I'm the unofficial answerer
## Not on my plate
- Anything in the ML platform
- Frontend code
- The mobile apps (we have a whole other org for that)
## Rules for this file
- Two primary projects max. If someone tries to add a third, push back.
- If a project has been in "research phase" for more than 4 weeks, something's wrong — either commit or kill it.
- Cross-team things go in their own section. Don't pretend they're mine.
memory-wiki/templates/engineer-wiki/STACK.md
+66
View File
@@ -0,0 +1,66 @@
# STACK
The company stack, not my personal preferences. Some of this I would not have chosen, but it's what we have.
## Languages
- **Go** — primary, all service code
- **Python** — data scripts, internal tooling, ML team's domain
- **SQL** — Postgres flavour, hand-written, reviewed like code
- **TypeScript** — only in the frontend monorepo, which I rarely touch
## Services
- Microservices, ~60 of them
- gRPC for service-to-service, REST/JSON at the edge
- Protobuf schemas in a shared `api` repo, versioned, reviewed across teams
- Service template is internal — don't scaffold from scratch, clone the template repo
## Data
- **Postgres** (primary, hosted) — per-service databases, no shared schemas across teams
- **Redis** — cache, rate limiting, some short-lived queues
- **Kafka** — event bus, source of truth for cross-service events
- **ClickHouse** — analytics, owned by the data platform team, I write queries but don't operate it
- **S3** — blob storage, large artifacts
## Infra
- Kubernetes on AWS, one cluster per environment
- Terraform for everything infrastructure
- ArgoCD for deploys (GitOps)
- Datadog for metrics, traces, logs, alerts
- PagerDuty for on-call
## CI/CD
- GitHub Actions for build + test
- ArgoCD for the deploy side
- Required checks: lint, unit, integration, protobuf breaking-change detector
- Deploys happen continuously, no deploy windows
## Auth / security
- Internal identity service (the one we're migrating to)
- mTLS for service-to-service
- Vault for secrets
- No secrets in env vars, ever
## Observability
- Datadog APM on every service
- OpenTelemetry for traces, exported via the collector
- Structured logging (JSON), correlation IDs on every request
- p99 latency and error rate are the two metrics I care about most
## Local dev
- One big `docker-compose.dev.yml` for the services my team owns
- Remote dev environments (via an internal tool) for cross-team work
- I do NOT run all 60 services locally — nobody does
## AI / agents
- OpenClaw 2026.4.11 for personal use (code review, design doc feedback, incident narration)
- Local Ollama models when I'm offline or the corporate proxy is being slow
- No AI-generated code merged without a human PR review — company policy
memory-wiki/templates/engineer-wiki/WORKING.md
+38
View File
@@ -0,0 +1,38 @@
# WORKING
> This is the only file the agent is allowed to overwrite. Everything else is human-maintained.
Last updated: 2026-04-13
## Current focus
Identity service migration — the checkout team is the last hard one. Everything else on my plate is second priority until they're unblocked.
## In flight this week
- [ ] Review the session-cookie compatibility shim PR from the checkout team
- [ ] Write the design doc for p99 latency cuts on the data access layer — two candidate approaches
- [ ] Pair with one of the mids on their oncall-playbook refresh for the Kafka lag alert
- [x] Deprecation timeline for legacy users service shared in #platform
- [x] Memory-wiki wired into my personal OpenClaw agent
## Blocked / waiting
- Waiting on data platform team to confirm the Kafka upgrade window for next month — blocks the identity service final cutover
- Waiting on security review of the new mTLS config for the migration — filed Tuesday, their SLA is 5 business days
## On-call / incidents
- I'm on primary rotation next week (April 20-26)
- Last week's p1: Redis failover on the notifications service, root cause was a connection pool exhaustion on the client side. Fix is in, postmortem draft is in the shared doc.
## Next up (not started)
- Retire the old deploy webhook handler — it's been shadowed by ArgoCD for three months, nobody uses it, pull it out
- Look into the ClickHouse query that feeds the platform-health dashboard, it got 4x slower after their schema change
## Notes for next session
- Do not let the p99 design doc slip to next month — it slipped last month, can't slip again
- When pairing on the oncall-playbook refresh, remember the new hire doesn't know what "quorum loss" means yet — define terms
- If checkout team pushes back again on the shim, escalate to their tech lead, don't try to negotiate it myself
memory-wiki/templates/solo-founder-wiki/DECISIONS.md
+44
View File
@@ -0,0 +1,44 @@
# DECISIONS
Append-only. Never delete an entry — if a decision is reversed, add a new entry that says so and reference the original by date.
Format:
```
## YYYY-MM-DD — short title
Decision: ...
Why: ...
Trade-off accepted: ...
```
---
## 2025-11-14 — Subscriptions for primary product, one-time for secondary
Decision: Primary product is monthly subscription, secondary product is one-time bundles.
Why: Primary has ongoing API costs per user (LLM calls). Secondary has near-zero marginal cost after sale.
Trade-off accepted: Two Stripe configurations to maintain, two different refund flows.
## 2025-12-02 — No freemium on primary product
Decision: 7-day trial with card on file, no free tier.
Why: Free tier users never converted at a rate that paid for their costs.
Trade-off accepted: Lower top-of-funnel signups, better economics on who does sign up.
## 2026-01-18 — Stay on Postgres, do not switch to SQLite + LiteFS
Decision: Keep hosted Postgres.
Why: I tried LiteFS for a weekend and the replication edge cases cost me a full day. Postgres is boring and works.
Trade-off accepted: $20/mo more than the SQLite path.
## 2026-02-09 — OpenClaw as primary agent runner, not Cursor or plain API
Decision: Daily driver for all agent work is OpenClaw.
Why: I want local-first, I want to own the memory layer, and SOUL.md is portable in a way that IDE-specific configs aren't.
Trade-off accepted: Fewer visual niceties than commercial IDE integrations.
## 2026-03-04 — Kill the mobile app idea for primary product
Decision: No mobile app for primary product in 2026.
Why: 92% of usage is desktop. Mobile would be six weeks of work for maybe 3% more revenue.
Trade-off accepted: Some users will complain. They can use the mobile web version.
## 2026-04-01 — Adopt the memory-wiki pattern for all my agents
Decision: Wire a memory-wiki into every OpenClaw agent I run.
Why: Session startup token cost was eating $3-5/day in API calls before the agent said anything useful.
Trade-off accepted: I have to actually maintain the wiki. Reviewing it every Monday.
memory-wiki/templates/solo-founder-wiki/PEOPLE.md
+24
View File
@@ -0,0 +1,24 @@
# PEOPLE
Humans I work with often enough that the agent should recognise the name. Not a CRM — keep it short.
## Core
- **{{NAME}}** — me, the user. Everything else in this wiki is about me.
## Contractors
- **Designer (part-time)** — Landing pages, illustrations, Figma files. ~4 hours a week. Communicates via Telegram. Lives in a different timezone, async only.
## Collaborators / advisors
- **Fellow indie hacker friend** — We swap funnel numbers and post-mortems weekly. No formal arrangement.
## Customers worth remembering
- Two enterprise-ish customers on the primary product who pay more than average and occasionally ask for custom features. If they email, the agent should flag it, not auto-reply.
## Rules for this file
- Real names go in a private note, not in the wiki. This file gets committed — don't leak anyone.
- If someone stops being relevant for 3 months, remove them from the file. Git remembers.
memory-wiki/templates/solo-founder-wiki/PROFILE.md
+42
View File
@@ -0,0 +1,42 @@
# PROFILE
## Who
- **Name:** {{NAME}}
- **Handle:** @{{HANDLE}}
- **Location:** Istanbul, TR (UTC+3)
- **Role:** Solo founder, indie hacker
## What I do
I build small, profitable SaaS products on my own. Two live products right now (see PROJECTS.md). Both are OpenClaw-native — I use agents as daily collaborators, not as a novelty.
I do the code, the copy, the billing, and the support. No co-founder, no team. One part-time contractor for design when I need it.
## Goals (2026)
- Get combined MRR past $10K by end of Q3
- Ship one new product end-to-end in under 6 weeks
- Cut my own "reinvent the wheel" time by leaning on OpenClaw agents for repetitive work
- Write in public once a week — no more silent months
## Non-goals
- Raising money. Bootstrapped on purpose.
- Hiring full-time employees this year.
- Expanding into enterprise sales. Self-serve only.
- Rewriting working products in trendier stacks.
## How I work
- Deep work mornings (06:00–12:00 TR), admin + calls afternoons
- Ship on Fridays when possible, never on Fridays after 17:00
- Prefer boring tech that I can debug at 2am
- Write decisions down in DECISIONS.md before committing to them
## What to tell the agent
- Default to English in replies, even when I write in Turkish
- Assume I already know the basics — skip "first, let me explain what Stripe is"
- Push back when I'm being lazy or hand-wavy
- Never invent metrics. If you don't know a number, say "unknown" and offer to go fetch it
memory-wiki/templates/solo-founder-wiki/PROJECTS.md
+39
View File
@@ -0,0 +1,39 @@
# PROJECTS
Active work. One-liner each, then context. Anything archived gets deleted from this file — check git history if you need the old entries.
## {{MAIN_PROJECT}} (primary)
**One-liner:** AI-powered {{MAIN_PROJECT}} that turns plain English into production-ready output.
- **Status:** Live, paying customers
- **MRR:** ~$3.7K and climbing
- **Stack:** Next.js, Postgres, Stripe subscriptions, Mixpanel
- **Repo:** `github.com/{{HANDLE}}/{{MAIN_PROJECT}}` (private)
- **Main bottleneck right now:** signup → trial conversion is stuck around 3–4%
- **Next bet:** rework the onboarding modal to show value before asking for a card
## side-project-two
**One-liner:** One-time-purchase builder that packages OpenClaw agents for non-devs.
- **Status:** Live, ~$300/week in one-time sales
- **Pricing:** $9 / $19 / $29 bundles, no subscriptions
- **Stack:** Same as above, minus the subscription logic
- **Main bottleneck:** free → paid is 12%, want 20%
- **Next bet:** upgrade modal the first time a free user hits the export limit
## Experiments (not products yet)
- **ios-agent-runner** — on-device LLM app, llama.cpp + Swift, "LM Studio for iPhone". Nights and weekends. No revenue yet, no timeline.
- **monitoring-dashboard** — internal tool that might become a product if I like it after 30 days of using it myself.
## Dead / archived
Nothing lives here. If it's dead, delete it from the file and let git remember.
## Rules for this file
- If a project stops making money for two full months, it moves to "Experiments" or gets killed outright
- If an experiment doesn't become a product in 90 days, it gets killed
- Never list more than 2 live products. Focus beats optionality.
memory-wiki/templates/solo-founder-wiki/STACK.md
+69
View File
@@ -0,0 +1,69 @@
# STACK
Everything I reach for by default. If you're proposing something not on this list, justify the switch.
## Languages
- **TypeScript** — primary, for everything web
- **Python** — scripts, analytics, one-off data work
- **Bash** — glue, deploy scripts
## Web / frontend
- Next.js 15 (App Router)
- Tailwind CSS
- shadcn/ui for components
- Framer for landing pages (non-devs can edit without asking me)
## Backend / data
- Node.js runtime, TypeScript everywhere
- Postgres (hosted) for relational data
- Prisma for schema + migrations
- Redis for rate limiting and session cache
## Infra
- Vercel for web apps and API routes
- Cloudflare for DNS, R2 for object storage
- GitHub Actions for CI
- No Kubernetes, no Docker Compose circus — keep it flat
## Payments
- Stripe Checkout for subscriptions and one-time
- Webhook handler logs every event to Postgres before acting on it
- Refund policy: no-questions-asked within 7 days
## Analytics / observability
- Mixpanel for product analytics (free plan, Export API + local Python)
- GA4 for marketing pages
- Google Search Console for SEO
- Sentry for errors
- Plain log files for everything else
## Auth
- Firebase Auth for consumer products
- Magic links preferred over passwords
## AI / agents
- OpenClaw 2026.4.11 as the daily driver
- Local Ollama models (gemma4, qwen3) when I don't want to burn API credits
- Frontier API only for the hard stuff — research, long-form writing, code review
## Tools I actually open every day
- VS Code
- iTerm2 + zsh
- Linear for personal tasks
- Notion for reports and runbooks
- Telegram for mobile notifications from my own bots
## Banned list
- ORMs that hide SQL completely — I want to see the query
- Anything that requires a docker-compose file to run locally
- Frameworks younger than 6 months in production
memory-wiki/templates/solo-founder-wiki/WORKING.md
+34
View File
@@ -0,0 +1,34 @@
# WORKING
> This is the only file the agent is allowed to overwrite. Everything else is human-maintained.
Last updated: 2026-04-13
## Current focus
Primary product, onboarding funnel. The signup → trial conversion is stuck at 3-4% and that's the single biggest lever for MRR this quarter.
## In flight this week
- [ ] Rework the trial welcome modal — 3 steps, show value before asking for payment
- [ ] Wire Mixpanel events for each step of the modal (`Welcome Modal Shown`, `Step Completed`, `CTA Clicked`)
- [ ] Ship the upgrade prompt on the secondary product's export limit
- [x] Memory-wiki wired into daily-driver OpenClaw agent
- [x] Weekly analytics script updated to include welcome-modal funnel
## Blocked / waiting
- GitHub referral banner PR on the secondary product — waiting on my own review, merge by Wednesday
- Vercel env migration for the new Postgres region — needs a 10-minute downtime window, scheduling for Friday morning
## Next up (not started)
- Programmatic SEO: comparison pages for the top 5 competitors on the primary product
- Reddit monitor agent: daily scan of 3 subreddits for mentions, Telegram alerts
- Rewrite the pricing page copy — current copy is 6 months stale
## Notes for next session
- If the welcome modal funnel is still flat after 3 days of data, try variant B (skip the pricing preview entirely)
- Don't forget to ping the open referral-banner PR before EOD Wednesday
- Check if the Stripe webhook rebuild from last week is still logging every event before acting
skills/claude/README.md
+40 -14
View File
@@ -1,32 +1,58 @@
# Claude Skills — Claude Code
Skills for [Claude Code](https://claude.com/claude-code) — invoked via `/skill-name` slash commands or automatic triggers based on the description.
Skills for [Claude Code](https://claude.com/claude-code) — invoked via `/skill-name` slash commands or automatically triggered by Claude based on each skill's `description` frontmatter.
## How to install
Tested against Claude Code on Opus 4.6 and Sonnet 4.6 (OpenClaw 2026.4.11 ecosystem).
Copy any skill folder into `~/.claude/skills/`:
## Skills in this folder
```bash
cp -r skill-name ~/.claude/skills/
```
| Skill | What it does | Install |
|---|---|---|
| [git-commit-writer](./git-commit-writer/) | Drafts an opinionated commit message from your staged diff, matching the repo's existing convention. | `cp -r skills/claude/git-commit-writer ~/.claude/skills/` |
| [openclaw-debugger](./openclaw-debugger/) | Walks the standard OpenClaw agent diagnosis checklist (gateway, logs, heartbeat, sessions, model provider) and prints a fix. | `cp -r skills/claude/openclaw-debugger ~/.claude/skills/` |
| [model-cost-compare](./model-cost-compare/) | Estimates token cost for a task across Opus 4.6, Sonnet 4.6, GLM-5.1, Minimax M2.7, and local Gemma 4, then recommends the cheapest capable model. | `cp -r skills/claude/model-cost-compare ~/.claude/skills/` |
| [excalidraw-architecture](./excalidraw-architecture/) | Generates or updates `docs/architecture.excalidraw` by surveying the codebase's entry points and data stores. Inspired by @bibryam. | `cp -r skills/claude/excalidraw-architecture ~/.claude/skills/` |
| [cost-optimizer](./cost-optimizer/) | Static audit of a project for the common Claude Code cost leaks — bloated CLAUDE.md, memory, cache-busting hooks, over-pinned Opus. | `cp -r skills/claude/cost-optimizer ~/.claude/skills/` |
The skill is immediately available. Invoke with `/skill-name` or let Claude trigger it automatically based on the description.
## How invocation works
## Format
After copying a skill into `~/.claude/skills/`, it's immediately available. You can:
Each skill is a single Markdown file with YAML frontmatter:
- **Explicit invocation:** type `/skill-name` followed by any arguments.
- **Auto-invocation:** just describe what you need in natural language. Claude reads every skill's `description` field and picks the matching one. That's why writing a precise, trigger-heavy description is the most important thing when authoring a skill.
## Format reference
Each skill lives in its own folder as `SKILL.md` — a single Markdown file with YAML frontmatter:
```markdown
---
name: skill-name
description: When to trigger this skill
description: When to trigger this skill (one specific sentence — Claude auto-invokes based on this).
---
# Instructions
# Skill title
What the skill should do...
## When to use
- ...
## Instructions
Concrete steps. Can reference Bash, Read, Edit, Grep, Glob, Write.
## Example invocations
- `/skill-name arg`
- "Natural language trigger"
```
## Skills coming soon
Keep skills between 80 and 200 lines. Longer than that and you're writing docs, not a skill.
This folder is a placeholder for Claude Code skills. Add yours via PR.
## Contribute your own
Have a Claude Code skill that's earned its keep in your workflow? Open a PR:
1. Create `skills/claude/<your-skill-name>/SKILL.md` following the format above.
2. Add a row to the table in this README.
3. Include a "When to use" section with concrete trigger phrases — this is what makes auto-invocation work.
4. Keep it under 200 lines. If it's bigger, it probably wants to be split into multiple skills.
PRs welcome at [mergisi/awesome-openclaw-agents](https://github.com/mergisi/awesome-openclaw-agents).
skills/claude/cost-optimizer/SKILL.md
+119
View File
@@ -0,0 +1,119 @@
---
name: cost-optimizer
description: Trigger when the user asks to audit Claude Code costs, reduce token spend, says "my Claude bill is too high", "optimize my CLAUDE.md", "why is this project burning tokens", or "/cost-optimizer". Scans a project for the common Claude Code cost leaks and returns a prioritized fix list.
---
# Cost Optimizer
Audit a project's Claude Code setup for the handful of well-known cost leaks and output a prioritized remediation list. This is a static inspection — no pricing API calls, no guesswork about past spend.
## When to use
- "My Claude Code bill doubled this month — what's going on?"
- "Audit this project for token waste"
- "Why is my session context always huge?"
- Post-mortem after a runaway agent run
## What to check
Run each check and record `PASS` / `WARN` / `FAIL` with a short note.
### 1. CLAUDE.md size
```bash
wc -l CLAUDE.md .claude/CLAUDE.md 2>/dev/null
```
- **PASS:** under 100 lines
- **WARN:** 100-300 lines
- **FAIL:** >300 lines — this is prepended to every message, so every line costs tokens forever.
Fix: move reference material (API keys, runbooks, verbose examples) into skill files or `docs/`, and leave CLAUDE.md as a thin pointer.
### 2. Memory file bloat
```bash
find ~/.claude/projects -name 'MEMORY.md' -exec wc -l {} \;
find .claude/memory -type f -exec wc -l {} \; 2>/dev/null
```
- **WARN** if any memory file is >500 lines.
- **FAIL** if >1500 lines — memory should be a curated index with links to detail files, not a dump.
Fix: extract old sections into `memory/<topic>.md` detail files and link from the index.
### 3. Unused or shadowed skills
```bash
ls ~/.claude/skills/ .claude/skills/ 2>/dev/null
```
- Cross-reference with the skill invocations in the last 30 days of shell history or session logs if available.
- Skills that have never been invoked but have huge `SKILL.md` bodies (>300 lines) are loaded into the skill index every turn — prune them.
### 4. Subagent fan-out patterns
Grep the project for Task/agent launch patterns:
```bash
grep -rn 'TaskCreate\|subagent\|parallel.*agent' --include='*.md' --include='*.js' --include='*.ts' .
```
- **WARN** if the repo spawns >5 parallel subagents per run without aggregation — each spins up its own context window.
- **FAIL** if subagents re-read the whole repo instead of receiving a scoped prompt.
Fix: pass a short brief + a handful of file paths to each subagent, not the entire CLAUDE.md context.
### 5. Prompt cache hygiene
Look for `.claude/settings.json` and check if the project sets an unusually short cache TTL, or if hooks invalidate the cache every message (e.g. a hook that echoes a timestamp into the system prompt).
- **FAIL** any hook that injects `date` / `uuidgen` / random content into every turn — it kills the cache, 10x cost.
### 6. Model selection
Grep for explicit model pins:
```bash
grep -rn 'opus\|sonnet\|haiku\|claude-3\|claude-4' .claude/ CLAUDE.md 2>/dev/null
```
- **WARN** if Opus is pinned for routine tasks that Sonnet could handle. Recommend the `/model-cost-compare` skill for a per-task estimate.
### 7. Session file size
```bash
du -sh ~/.claude/projects/*/sessions 2>/dev/null | sort -h | tail -5
```
Huge session dirs suggest you never `/compact` long-running threads. Suggest periodic compaction.
## Output format
Print a ranked list. Top of the list = biggest win per effort.
```
Cost Optimizer — <project>
Priority 1 (FAIL)
[CLAUDE.md] 412 lines — prepended every turn. Extract sections into skills/.
[cache hygiene] .claude/settings.json hook injects `date +%s` on SessionStart. Remove it.
Priority 2 (WARN)
[memory] MEMORY.md is 820 lines. Index top, details linked.
[model pinning] Opus 4.6 pinned in 4 skill files — 2 could drop to Sonnet 4.6.
Priority 3 (nice-to-have)
[skills] 3 skills (haiku-card, foo, bar) never invoked in last 30 days.
Estimated impact: roughly halving per-turn overhead — validate with a before/after /cost check.
```
Do not invent dollar savings. You can estimate relative impact ("~30% smaller context") but not absolute currency unless the user provides their current bill.
## Example invocations
- `/cost-optimizer`
- "Audit this project for Claude Code cost waste"
- "My CLAUDE.md feels too big — what should I cut?"
- "Why is my prompt cache missing every turn?"
skills/claude/excalidraw-architecture/SKILL.md
+61
View File
@@ -0,0 +1,61 @@
---
name: excalidraw-architecture
description: Trigger when the user asks for an architecture diagram, says "draw the system", "update the architecture diagram", "give me an excalidraw of this codebase", or "/excalidraw-architecture". Generates or updates an Excalidraw JSON file at docs/architecture.excalidraw by reading the codebase's key entry points.
---
# Excalidraw Architecture
Produce an architecture diagram of the current project as an Excalidraw file (`docs/architecture.excalidraw`). The diagram shows services, entry points, data stores, and the edges between them — the kind of whiteboard sketch you'd draw in a design review.
Inspired by Bilgin Ibryam's Medium post on "Architecture diagrams as code with Claude Code + Excalidraw" — credit: [@bibryam](https://medium.com/@bibryam). This skill is a lightweight reimplementation for OpenClaw-style repos.
## When to use
- New contributor asks "what does this repo look like?"
- User wants to update a stale architecture diagram after a refactor
- User says "draw me the system", "excalidraw the backend", "/excalidraw-architecture"
- Preparing a design doc and needs a canonical diagram
## Instructions
1. **Survey the codebase.** Use Glob and Grep to identify:
- Entry points: `main.*`, `index.*`, `server.*`, `api/**/route.*`, `cmd/*/main.go`, `package.json` "scripts" field, `Dockerfile` `CMD`.
- Data stores: mentions of `postgres`, `redis`, `convex`, `sqlite`, `s3`, `mongodb`, `prisma`.
- External services: Stripe, OpenAI, Anthropic, Twilio, SendGrid, webhook handlers.
- Internal modules: top-level folders under `src/`, `app/`, `lib/`, `agents/`.
Read at most 3-5 key files to confirm how the pieces connect — don't try to read the whole repo.
2. **Sketch the model mentally.** List nodes (rectangles) and edges (arrows with labels like "HTTP", "SQL", "pub/sub"). Group related nodes into clusters.
3. **Generate the Excalidraw JSON.** The file format is standard Excalidraw:
```json
{
"type": "excalidraw",
"version": 2,
"source": "https://excalidraw.com",
"elements": [ /* rectangle, arrow, text elements */ ],
"appState": { "viewBackgroundColor": "#ffffff", "gridSize": 20 },
"files": {}
}
```
Each element needs at minimum: `id`, `type` (`rectangle` / `arrow` / `text` / `ellipse`), `x`, `y`, `width`, `height`, `angle: 0`, `strokeColor`, `backgroundColor`, `fillStyle`, `strokeWidth`, `roughness`, `opacity`, `seed`, `versionNonce`, `isDeleted: false`, `groupIds: []`, `boundElements`, `updated`, `link: null`, `locked: false`. For text elements add `text`, `fontSize`, `fontFamily`, `textAlign`, `verticalAlign`. For arrows add `points`, `startBinding`, `endBinding`. Use integer pixel coordinates on a ~20px grid. Arrange nodes left-to-right by data flow.
4. **Do not hand-forge exotic fields you're unsure about.** If a field is optional and you're not confident, omit it — Excalidraw is forgiving on load. When in doubt, open the resulting file in the Excalidraw web app and confirm it renders; fix any errors it reports.
5. **Write the file** to `docs/architecture.excalidraw` using the Write tool. If the directory doesn't exist, create it first with `mkdir -p docs`.
6. **Offer to open it.** Suggest the user run:
```bash
open docs/architecture.excalidraw # macOS — opens in Excalidraw desktop app if installed
```
Or drag-drop into [excalidraw.com](https://excalidraw.com).
7. **Update vs regenerate.** If `docs/architecture.excalidraw` already exists, read it first. If the existing layout still fits, only add/move the nodes that changed. If the shape of the system has changed significantly, tell the user and regenerate from scratch.
## Style guidelines
- Rectangles for services, ellipses for datastores, small rectangles with dashed stroke for external SaaS.
- Arrows labelled with the protocol (`HTTP`, `gRPC`, `SQL`, `webhook`).
- Max ~15 nodes. If the system is bigger, produce a top-level diagram and suggest follow-up per-subsystem diagrams.
- Leave a title text element at the top: `<repo name> — architecture (generated <date>)`.
## Example invocations
- `/excalidraw-architecture`
- "Draw the architecture of this repo"
- "Update docs/architecture.excalidraw — I just added a Redis queue"
- "Give me an excalidraw diagram of how the OpenClaw gateway talks to agents"
skills/claude/git-commit-writer/SKILL.md
+47
View File
@@ -0,0 +1,47 @@
---
name: git-commit-writer
description: Trigger when the user asks to write a commit message, generate a commit from staged changes, review a diff before committing, or says "/commit". Reads git diff --staged and produces an opinionated, convention-matching commit message.
---
# Git Commit Writer
Generate a disciplined commit message from the currently staged changes. Opinionated about style: imperative mood, concise title, body that explains **why** not **what**.
## When to use
- User says "write a commit message", "/commit", "commit this"
- User has staged changes and asks to review them before committing
- User asks "what should this commit be called"
Do NOT use this skill to actually run `git commit` unless the user explicitly asks — just draft the message and show it.
## Instructions
1. Run `git status --short` with the Bash tool. Confirm there are staged changes. If nothing is staged, stop and tell the user.
2. Run `git diff --staged` to read the full staged diff. If the diff is large (>500 lines), also run `git diff --staged --stat` to get a file-level overview first.
3. Run `git log --oneline -10` to learn the repo's commit convention. Look for:
- Conventional Commits prefixes (`feat:`, `fix:`, `chore:`) — if present, match the style.
- Title case vs sentence case.
- Whether bodies are used or not.
- Any ticket / issue prefix (e.g. `[PROJ-123]`).
4. Draft a message following these rules:
- **Title:** imperative mood ("Add X", not "Added X" or "Adds X"), max 70 characters, no trailing period.
- **Body (if needed):** blank line after title, then 1-3 short paragraphs or bullets explaining *why* the change is necessary, what problem it solves, what trade-offs were made.
- **Never** use the word "refactor" alone — always say what was refactored and why ("Extract retry loop into helper to share with job runner").
- **Never** write "Update file.js" — describe the behavior change, not the file touched.
- **Never** invent a ticket number. If the repo uses them but you can't infer one, leave it out.
5. Show the drafted message in a fenced code block. Ask the user if they want you to run `git commit` with it. Do not commit automatically.
## Anti-patterns to reject
- "Various fixes" / "Updates" / "WIP" — reject and ask for specifics from the diff.
- "Refactor code" — must name the unit being refactored.
- Title >70 chars — shorten or move detail to body.
- Past tense or "-ing" forms — rewrite to imperative.
## Example invocations
- `/git-commit-writer`
- "Write a commit message for what I have staged"
- "Review my staged diff and draft a commit"
- "/commit — but don't push"
skills/claude/model-cost-compare/SKILL.md
+80
View File
@@ -0,0 +1,80 @@
---
name: model-cost-compare
description: Trigger when the user asks which model to use, wants to compare model costs, says "what's cheapest for this task", "should I use Opus or Sonnet", "can a smaller model handle this", or "/model-cost-compare". Estimates token cost across Opus 4.6, Sonnet 4.6, GLM-5.1, Minimax M2.7, and local Gemma 4, then recommends the cheapest model capable of the task.
---
# Model Cost Compare
Given a task description (and optionally a rough prompt / input size), estimate the cost of running it on each available model tier and recommend the cheapest one that can actually do the job.
## When to use
- "Which model should I use for X?"
- "Is it worth running this on Opus or will Sonnet do?"
- "Can I offload this to a local model?"
- "/model-cost-compare — classify 10k support tickets"
## Pricing table (indicative — always flag as "check provider docs")
Use these rough figures. They are **not** exact; confirm before quoting real numbers to the user.
| Model | Tier | Input ($/1M tok) | Output ($/1M tok) | Context | Strengths |
|---|---|---|---|---|---|
| Opus 4.6 (1M) | Frontier | ~$15 | ~$75 | 1M | Agentic, long-context, hard reasoning |
| Sonnet 4.6 | Mid | ~$3 | ~$15 | 400k | Everyday coding, agents, drafting |
| GLM-5.1 | Budget hosted | ~$0.60 | ~$2.20 | 256k | Cheap bulk work, decent reasoning |
| Minimax M2.7 | Budget hosted | ~$0.40 | ~$1.80 | 256k | Very cheap, OK for templated output |
| Gemma 4 (local) | On device | $0 marginal | $0 marginal | 32k | Free but slow, weak at multi-step logic |
> Indicative pricing as of OpenClaw 2026.4.11. Check the provider docs before billing decisions.
## Instructions
1. Parse the user's task. Extract:
- **Task type:** reasoning, extraction, classification, drafting, translation, agentic tool use, long-context synthesis.
- **Input size estimate:** in tokens. If the user says "10k tickets averaging 500 tokens", that's 5M input tokens. If unknown, ask for a rough size.
- **Output size estimate:** short label? full essay? JSON record?
- **Volume:** one-off or batch?
2. Rule out incapable models. Use this capability floor:
- Agentic multi-tool flows with long reasoning → Opus or Sonnet only.
- Structured extraction / classification with clear schema → any tier, including Gemma 4 local.
- Long-context synthesis (>400k tokens) → Opus only.
- Privacy-sensitive data that cannot leave the machine → Gemma 4 local only.
3. For each surviving model, compute:
```
cost = (input_tokens / 1_000_000) * input_price
+ (output_tokens / 1_000_000) * output_price
```
Multiply by volume. Show your arithmetic so the user can sanity-check.
4. Print the comparison as a Markdown table sorted cheapest first. Bold the recommended row.
5. End with a one-line recommendation: `Recommended: <model> — <1-sentence reason>`.
## Output example
Input: "Classify 10,000 customer support emails into 5 categories. Avg 400 input tokens, 20 output tokens."
```
Total tokens: 4M input, 200k output
| Model | Input cost | Output cost | Total | Capable? |
|-------------|-----------:|------------:|--------:|---------:|
| **Gemma 4** | $0.00 | $0.00 | $0.00 | yes |
| Minimax M2.7| $1.60 | $0.36 | $1.96 | yes |
| GLM-5.1 | $2.40 | $0.44 | $2.84 | yes |
| Sonnet 4.6 | $12.00 | $3.00 | $15.00 | yes |
| Opus 4.6 | $60.00 | $15.00 | $75.00 | overkill |
Recommended: Gemma 4 local — classification with a fixed 5-label schema is trivial for on-device models and costs nothing.
```
## Anti-patterns
- Don't recommend Opus by default "just to be safe". If Sonnet can do it, say so.
- Don't recommend a local model for agentic tool-use loops — they spiral.
- Always flag prices as approximate.
## Example invocations
- `/model-cost-compare classify 10k support tickets into 5 buckets`
- "What's the cheapest model that can draft 200 SEO meta descriptions a day?"
- "Should I use Opus or Sonnet for this 800k-token codebase review?"
skills/claude/openclaw-debugger/SKILL.md
+109
View File
@@ -0,0 +1,109 @@
---
name: openclaw-debugger
description: Trigger when an OpenClaw agent is broken, silent, crashing, stuck, not responding, returning empty output, or the user says "my agent is down", "agent not working", "/openclaw-debugger". Walks through the standard OpenClaw 2026.4 diagnosis checklist and prints a report.
---
# OpenClaw Debugger
Diagnose a broken OpenClaw agent (Orion, Echo, Radar, or any custom agent from `awesome-openclaw-agents`). Produces a structured diagnosis report identifying the most likely root cause.
Compatible with OpenClaw 2026.4.11 and later. For deeper reference see `TROUBLESHOOTING.md` in this repo.
## When to use
- Agent returns empty output or times out
- `openclaw agent --agent <name> --message "..."` hangs
- Heartbeat dashboard shows the agent as stale
- Model provider errors (429, 401, connection refused)
- User says "openclaw is broken" / "agent is down" / "why is Orion not replying"
## Instructions
Work through the checklist in order. Stop at the first failing step and report it — no need to run later steps until that's fixed.
### 1. Gateway health
```bash
openclaw agent --status
```
- If the gateway is down, tell the user to run `openclaw gateway restart`.
- If it reports "port 18789 in use by another process", find and kill the stale process (`lsof -i :18789`).
### 2. Tail recent logs
```bash
tail -n 200 ~/.openclaw/logs/gateway.log
tail -n 200 ~/.openclaw/agents/<name>/logs/agent.log
```
Grep for `ERROR`, `PANIC`, `401`, `429`, `timeout`. The first error in the tail is usually the real cause — everything after is fallout.
### 3. Heartbeat status
```bash
cat ~/.openclaw/agents/<name>/heartbeat.json
```
- Check `last_seen` timestamp. More than 5 minutes old = worker crashed.
- If `status` is `starting` for more than 60s, the agent is stuck in init (usually a bad `SOUL.md` or missing env var).
### 4. Session file integrity
```bash
ls -la ~/.openclaw/agents/<name>/sessions/sessions.json
```
- If the file is >5 MB, sessions may be corrupt. Back it up and delete:
```bash
mv ~/.openclaw/agents/<name>/sessions/sessions.json{,.bak}
```
- If the JSON is invalid (`python3 -m json.tool < sessions.json`), same fix.
### 5. Model provider reachability
Read `~/.openclaw/agents/<name>/SOUL.md` frontmatter to find the configured `model` and `provider`. Then:
- **Anthropic (Opus 4.6, Sonnet 4.6):** `echo $ANTHROPIC_API_KEY | head -c 10` — confirm key exists.
- **GLM-5.1 / Minimax M2.7:** check `~/.openclaw/providers.json` for the base URL and hit `/v1/models` with curl.
- **Gemma 4 local:** confirm Ollama or the local runtime is up (`curl localhost:11434/api/tags`).
A 401 means bad key. A 429 means you're rate limited — retry with exponential backoff or switch model. Connection refused on localhost means the local runtime crashed.
### 6. SOUL.md validity
Read the agent's `SOUL.md` and check:
- YAML frontmatter parses (must have `name`, `model`, `system_prompt` fields)
- `model` string matches one in `~/.openclaw/providers.json`
- No lingering Turkish prompts if the agent is supposed to respond in English (per repo rules)
## Output format
Print a diagnosis report like this:
```
OpenClaw Debugger — <agent-name>
[OK] Gateway up (port 18789)
[OK] Logs clean
[FAIL] Heartbeat stale (last_seen 14 min ago)
[SKIP] Session file
[SKIP] Model provider
[SKIP] SOUL.md
Root cause: worker process crashed ~14 min ago. Last log line:
ERROR 2026-04-13T08:41:02 panic: model provider returned 401
Fix:
1. Export a fresh ANTHROPIC_API_KEY
2. openclaw gateway restart
3. openclaw agent --agent <name> --message "ping"
```
Keep it terse. The user wants a fix, not an essay.
## Example invocations
- `/openclaw-debugger orion`
- "My Echo agent is stuck — debug it"
- "Why is `openclaw agent --agent radar` timing out?"