DEV Community: minixspace

Diary of a Shrimp Keeper: Band of Brothers

minixspace — Fri, 02 Oct 2026 08:20:42 +0000

-- Putting a squad together inside opencode

"We few, we happy few, we band of brothers;
For he to-day that sheds his blood with me
Shall be my brother."

Stirring stuff. Brothers-in-arms, shoulder to shoulder, ready to die for one another — what a glorious notion!

...and then my heroic daydream popped. I glanced back at the coding task my AI had been grinding on, and — good grief — it had been stuck for ages.

I looked over at my two shrimp, who had learned to watch each other's backs. If only the lads could form a squad and write code for me. Now that would be something.

I. One Shrimp Is No Army

For the past year or so, my approach to coding agents had been one long conversation, start to finish: requirements, design, coding, testing, review — all crammed into a single session.

At first it was great. It knew every martial art, every secret technique.

Then, slowly, the wrongness crept in.

One time I had it finish a design, then asked offhandedly: "So — what do you think of your own plan?"

"Overall the design is sound, module responsibilities are clear, extensibility is good..."

A whole paragraph of self-congratulation.

Then the chill hit me.

When a shrimp starts looking down on the world, drunk on its own brilliance, its end is near.

I mulled on that for a while. What had led my shrimp to lose its way? Same model, same context, watching itself — no wonder it had walled itself in.

And there was more than one fault at work:

Switching stances, and it stumbles. It plays designer, programmer, tester, researcher, all at once — and every switch costs something. Sure, you can switch on the fly, even spar with yourself, left hand against right. But it's too deep in the game to see its own stance. Someone outside has to point it out.
No eye for its own openings. Design and review run on the same context, from the same angle. Insight is exactly what's missing.
Too many arts, no staying power. Over hundreds of turns, the goal either slips its mind or drifts. And the moment context gets compressed, whatever rules we agreed on go out the window. The original intent is the first casualty.
Training without discipline. Where it should stop and ask, it charges ahead; where it should just decide, it asks permission for everything. Leave things vague, and the shrimp does whatever it likes.

On a battlefield, what matters is formation — who covers whom, who moves when. Our shrimp is a master of every martial art, blessed with godlike technique. But there's strength in numbers — and one swordsman against a hundred thousand leaves the odds rather grim.

I needed a squad.

At Agincourt, a small band of exhausted, outnumbered men held their formation and broke a French army many times their size. That's the trick: five who cover each other beat five hundred who don't.

So my squad should look like this:

A Captain, to command — formations, orders, the whole picture.
A Strategist, to plan — decisions made before the first move.
A Scout, to reconnoiter — intelligence before contact.
A Soldier, to fight — take the objective, hold the ground.
A Provost, to enforce — nothing slips past, nothing gets bent.

And a squad like that needs discipline:

Process (design, review, build, test, inspect — none optional): without discipline, nothing runs.
Division of labor (roles kept separate): each to their own post, each to their own strength.
Focus (isolated context): one job, one mind, undistracted.
Orders (documents on disk, immune to compression): issued once, followed exactly.

II. In Search of a Company

A few good men — that's what I needed.

A squad that could break a hundred thousand, take any objective, stand unbroken — that wish, I don't believe, was mine alone.

But drilling troops is not the work of a single day. Ordered dispatch, instant obedience, coordination up and down the line, seamless mutual cover. It takes a mature, stable framework — one that can build processes, dispatch subagents, pass messages, and manage context.

So I waited. The big shops will ship something any day now, I figured.

And while I waited, I went door to door among the great houses, working my way through every hot coding agent from the start of the year to the middle of it.

Claude Code: no room to maneuver

CC's Task tool genuinely spawns subagents, and they can run in the background. Solid machinery.

But back then its Agent Teams were still experimental, with one hard limitation: the whole team had to be cut from the same cloth — one model for everyone. No exceptions.

What I wanted was each to their strength — the sharpest reasoner on strategy and review, a code-specialized model on the front line, something cheap and quick on the errands. CC couldn't do it.

I gave up.

Codex: all talk, no squad

In June 2026, the Codex docs claimed role configuration was supported.

So I did it properly: six roles — architect, developer, explorer, orchestrator, reviewer, tester — a written collaboration manual, and a goal-mode run told to follow the book to the letter.

I was feeling pleased with myself. This is it, I thought.

Then the project log kept spitting out the same line:

"no subagents were spawned"

The "reviewer agent" was just the same session wearing a different hat. No independent context at all.

All that setup for nothing. I gave up.

kilo: roles you can switch, rules you can't write

kilo ships with code / ask / architect / debug roles, switched with a dropdown or a command like /architect.

You pick a role by hand, then give orders from inside that identity.

It used to have an Orchestrator mode that dispatched work automatically; later that became "each agent figures it out and calls subagents itself."

So dispatching work was never kilo's problem. The problem is that there's nowhere to put the process — how phases are gated, who reports back, which checkpoints need a human signature. None of that can be written down. It all comes down to whatever the model feels like doing.

OpenCode: at last, the right school

Then I tried OpenCode, and sat up straight.

A primary + subagent architecture: explicit dispatch, permission isolation, custom agents beyond the built-in Plan and Build — and, a different model per agent.

That's what I wanted. Real multi-agent support at the mechanism level, not just marketing.

There's also a ready-made multi-agent plugin in the ecosystem — OMO (oh-my-openagent) — so I installed it and took it for a spin: Sisyphus orchestrates, Prometheus runs the planning interview, Atlas executes, Oracle/Librarian/Explore handle odd jobs. Team Mode gives you parallel squads and a tmux view. The workflow is "interview → plan → /start-work", or just hand over everything with ultrawork.

Close to my thinking. Genuinely featureful.

But —

Eleven agents. Fifty-four-plus lifecycle hooks. I looked at the roster and realized I hadn't hired a squad. I'd hired an army.

And its playbook isn't mine: I wanted three gates only a human can sign off on (requirements, design, final acceptance), a reviewer with veto power, escalation after three rejections, and a paper trail in the war log. OMO is "let it run" — that layer of control just isn't there.

Fine. I'll train my own.

III. OCATeam: a Squad of Five

OpenCode gave me the machinery. It didn't give me the playbook.

So I wrote the playbook and the roles myself.

That's how OCATeam (OpenCode Agent Team) came about. A small squad, five strong:

 → orchestrator    — the Captain, primary agent, commands the squad, answers to you
    ├── architect  — the Strategist, plans only, system design
    ├── developer  — the Soldier, does the fighting: code + tests + bugfixes
    ├── reviewer   — the Provost, reviews only, hunts for flaws
    └── explorer   — the Scout, recon: docs, references, research

Three things had to be in place:

The roster (agents/ocat-*.md) — who does it: each role's model, permissions, and style. The Provost is read-only: no file edits, no shell. The Scout gets a small thinking budget — it's running errands, it doesn't need to philosophize.
The playbook (skills/ocat/SKILL.md) — how it's done: how phases are divided, where documents live, how many review rounds, when to escalate. The Captain's first move on any job is to load it.
The muster order (install.sh) — how to raise the squad: --global installs once for everything; --project installs into a single repo, version-controlled. After that, new projects are zero-config: hit Tab to switch to ocat-orchestrator, say the word, and the squad falls in.

The collaboration style is deliberately plain: everything goes into the war log.

All cross-agent communication runs through board files under .boards/ — the Captain keeps the overall progress board, each member keeps their own task board. Who did what, which revision the Provost bounced, how many tests ran: all in the file. Visible. Auditable.

The Rules of Engagement

Four phases. The checkpoints are configurable, but three of them need your signature, no exceptions:

Phase	What happens	Who	Sign-off
0: Clarify the orders	The Captain asks you questions until the requirement is nailed down in writing	Captain	🔒 required
1: Plan the campaign	The Strategist drafts the architecture and phases; the Provost reviews it; then you sign off	Strategist → Provost	🔒 required
2: Into the field	The Soldier executes; the Provost inspects after each objective	Soldier → Provost	🔓 optional
3: Debrief	Test acceptance + four-dimension final review, checked line by line against the original requirement	Soldier + Provost	🔒 required

Every cycle is "attack → inspect → repair → report back." Anything substandard goes back for rework (up to N rounds, configurable). If it still fails, the Captain escalates to you — and never just spins, burning tokens in a loop.

The Provost's rules are the part I hardened most. Four measuring sticks: first principles, alignment with user value, requirement traceability, and contamination detection (did anything get smuggled in that nobody asked for?).

Every round has to circle back to the original requirement. It's the cure for the classic "build first, drift later."

Four Lessons the Hard Way

Training the squad wasn't smooth sailing either. A few of the more instructive mishaps:

Lesson one: one extra line of thinking:, and all five dropped dead.

I gave every agent a thinking: <level> field. Declarative metadata, I assumed — just decoration.

OpenCode, it turns out, passes unrecognized fields straight through to the model provider. All five agents hit the deck with Upstream request failed, in perfect unison.

Deleted the line. They came back.

Lesson two: the pass didn't work.

I gave the Captain a carefully tuned bash whitelist — "ls *": allow and the like. Looked airtight. I figured that pass would keep the Captain from overstepping.

Reality: real commands look like ls /path/to/file, and the * in a glob doesn't match the / in a path. The catch-all rule wins every time. The whitelist was decorative.

Lesson three: whose orders win? Guessed wrong.

OpenCode accepts permissions in two places: the permission block at the top of an agent file, or the corresponding section in the project's opencode.json.

I assumed the latter — the project config — was "user settings," and would therefore override the former.

Reality slapped back: the agent file wins, and the opencode.json section is simply ignored. Open bash up in the JSON all you like — the Captain still pops a confirmation for every single command.

Two ways out: write permissions into the agent file where they belong, or use OpenCode's --auto to wave everything through (or hit ctrl-P in the TUI and set Permission to Auto).

Lesson four: a rename, and the whole thing broke.

I wanted a consistent dotted-prefix convention inside the project — boards/ → .boards/. Halfway through, I discovered .opencode/agents and .opencode/skills are untouchable: OpenCode's discovery glob hard-codes those two directory names.

So: halfway reverted, halfway kept. The Great Naming Unification is shelved indefinitely.

IV. Trial by Fire

The squad was assembled. But whether it could fight — that takes a battlefield.

So I deployed it into my own opencode and handed it work.

After the first dust settled, I felt the difference: the parts that should be confirmed (requirements) stop getting glossed over; the parts that should run themselves (build, test) just run. The Captain leads, and every phase — task, review, repair — rotates on its own.

What reassured me most: in design as in development, the Provost stays on duty and finds something real almost every round — passing usually takes more than one attempt. That iron impartiality is precisely what solo work lacks.

Of course, the playbook depends on a Skill, and ultimately on the model's judgment. A weak model can still ignore the rules and rubber-stamp its own work. With DeepSeek v4 Flash as my Captain, it's been smooth sailing.

Deployment is simple: run the muster order. --global installs once, available everywhere; --project <dir> installs into a single repo — good for teams that want one shared process, and it can be version-controlled.

Then in opencode, Tab over to ocat-orchestrator, state what you need, and the squad falls in behind you.

Three dials worth knowing:

Swap the crew: edit the model config in agents/ocat-xxx.md, globally or per project. The defaults are DeepSeek v4 Flash/Pro — back when I built this, it was cheap and generous; it may not be your best pick today. Just change it.
Add or drop roles: the active_agents list in .ocat.json at the project root. Remove what you don't need (small projects don't need a Scout) and the Captain stops sending work their way.
Tune the gates: same .ocat.json. gates decides which checkpoints need your signature; review.max_iterations caps how many rework rounds are allowed (default 3). Annoyed by bash confirmation prompts? Start with --auto and everything sails through.

The limitations are just as plain: it's built on OpenCode, so it doesn't port to other coding agents — though the method is general. Any framework with a primary/subagent API should adapt without much trouble. And it's designed for the full "requirements → design → build" pipeline; plenty of situations simply don't need that much ceremony.

Fortunately the process triggers on demand. The Captain isn't stupid — small jobs get handled on the spot, no fuss.

V. Everything Changes

One last note on timing, so I don't mislead anyone.

I built this a few months ago (June–July 2026), and every finding above reflects the versions of that moment.

According to Codex's official manuals as of now (September 2026), multi-agent and subagent support is stable and on by default, with spawn_agent, wait_agent, and per-agent model configuration all shipped.

So that old line — "Codex can't do real multi-agent" — expired a while ago.

Multi-agent teams are simply supported now, everywhere. The built-in "team" features across agentic coding tools will only get more flexible and more powerful. OCATeam's particular implementation will, in all likelihood, be replaced by something better.

What's worth keeping isn't the agent files. It's the playbook — the rules of engagement for how a handful of agents should work together.

Time washes everything downstream, tools included. But knowing how to get a team working together, and what rules to set — that pays off regardless.

You can train a squad of your own, suited to your own habits.

The code is open source: https://github.com/icoding2016/ocateam

git clone https://github.com/icoding2016/ocateam.git && cd ocateam
./install.sh --global

The field is wide, the banners snap in the wind.

We few, we happy few, we band of brothers.

Previously in this series

Diary of a Shrimp Keeper: The Great Famine

minixspace — Wed, 23 Sep 2026 12:34:23 +0000

Ever since Mini and Nano learned to work as a team (see Old Flame, New Love), I'd been feeling safe enough to play the hands-off keeper. Out of sight, out of mind.

I. The Price of Hands-Off Keeping

The automated jobs had been running fine for days, and with the two shrimp keeping an eye on each other, I simply let go for a few days and stopped checking.

Then one morning I casually glanced at Telegram — uh oh.

Both shrimp were out cold — they'd been cut off for two or three days. From howling with hunger at first to barely breathing now. A pitiful sight.

I slammed the table: who did this — who cut off my shrimp's food supply?!

II. Who Moved My Shrimp Food?

The rations I kept for the shrimp came from opencode's Go plan: $10 a month for $60 worth of API credit. For my two street-stall-raised shrimp, Mini and Nano, that was a feast for pennies — they were living large.

The trouble started on September 8th. opencode quietly changed the rules overnight.

It used to be that calling its API just needed an Authorization: Bearer <key>. Now there's a mandatory new header, x-opencode-session — miss it, and you get the cold shoulder in the form of:

HTTP 400: Error from provider (Console Go):
Request is missing x-opencode-session and cannot be routed efficiently.

The complaint letter Nano sent right before passing out spelled it out clearly:

⚠️ Cron 'techub-ops' failed:
HTTP 400: Request is missing x-opencode-session and cannot be routed efficiently.

Mini was no better off — pale as a sheet, hanging by a thread.

I rushed to check opencode's official docs — and sure enough, there it was, the new mandatory header, stated plainly.

A heads-up would've been nice, though. Changing a live protocol in a single changelog entry, with zero announcement? That's just not cool.

III. Roll Call

Angry or not, rescue comes first.

First, figure out exactly who went hungry this time.

Besides my two precious shrimp, Mini and Nano, I also had some scheduled scripts calling model APIs directly.

The culprit, of course, was the new x-opencode-session:

It's just a client-generated session identifier, an opaque string;
Keep the same value within a session, and opencode uses it to pin that session's requests to the same backend, so the prompt cache stays hot.

The docs say:

Send a stable session ID in x-opencode-session for each conversation so we can optimize routing and prompt caching.

But each agent vendor was at a different stage of supporting it. opencode published a list of "verified clients" — Hermes, Claude Code, Codex, Kilo Code, and the like.

Everyone has to buy their own ticket before they can ride.

Official notes here: https://opencode.ai/docs/go/#where-can-i-use-it

On my side, three casualties:

Task	How it connects	Why it broke
Scripts calling the API directly	Raw HTTP	No such layer in the code at all — requests naturally carried no session header
Nano's ops patrol	Hermes	The current Hermes release (v020) can't send a Session ID
Mini's daily jobs	OpenClaw	My OpenClaw doesn't support Session IDs either

IV. Emergency Rescue

Situation mapped. Time for triage.

First, Order Takeout

If the opencode plan is what's broken, order food from somewhere else to stop the bleeding.

Switch the default provider to OpenRouter and get the dead jobs running again.

Upgrade: Nano Back to Full Health

Nano's case was much simpler. Hermes was on opencode's official "verified clients" list. Hermes v021 already shipped the matching patch — upgrade it, and the problem should go away.

Upgrade, restart, call out to my beloved shrimp. Nano let out a long sigh and slowly came back to life.

Patch: A Temporary Meal Ticket for Mini

Mini was trickier. It didn't support the header yet — I checked the latest release, and there wasn't a trace of x-opencode anywhere in the package.

If the official fix won't come, do it yourself: inject a hardcoded session identifier into the request headers as a stopgap.

In openclaw.json, add a headers declaration to the opencode entry under models.providers:

"headers": {
  "x-opencode-session": "hungry-openclaw-********"
}

With the temporary meal ticket in hand, Mini opened its eyes, like waking from another lifetime.

A temporary meal ticket is for emergencies only.

The session ID was only ever a self-assigned client label — as long as it's stable and non-empty, the server accepts it. No issuing authority required.

The cost: a hardcoded value means every session shares one routing identifier, so you lose the cache bonus of pinning each session to its own backend. Hit rates take a hit.

Good enough for now. Wait for the official patch.

Same Prescription, Different Patient

With Mini awake, it was my own scripts' turn.

Same prescription as Mini's: get the scheduled jobs' LLM client its own meal ticket too:

headers = None
if api_base and "opencode.ai" in api_base:
    sess = os.getenv("OPENCODE_SESSION_ID") or uuid.uuid4().hex[:12]
    headers = {
        "x-opencode-session": f"hungry-shrimp-{sess}",
        "User-Agent": "opencode-you-own-me-a-meal/1.0",
    }
client = OpenAI(api_key=api_key, base_url=api_base, default_headers=headers)

With that fixed, I fired off a request at opencode's front door — and opencode answered like nothing had ever happened.

Done.

V. After the Pain

Both shrimp were rescued without lasting damage, and the jobs were running again.

Still, two or three days of famine left a mark. The scheduled jobs were down for two days — no real harm done, but it stung.

What if, someday, I'm a world-famous guru with earth-shattering services running on my machines? Two days of downtime would be a catastrophe...

ahem... getting ahead of myself...

Either way: don't put all your eggs in one basket.

Two providers on standby, primary-plus-backup routing with automatic failover in the scripts — set it all up now.

Next time some provider tries to pull a fast one on me — bring it on.

Previously:
· Diary of a Shrimp Keeper: My OpenClaw Misadventures
· Diary of a Shrimp Keeper: Old Flame, New Love

Diary of a Shrimp Keeper: Old Flame, New Love

minixspace — Tue, 22 Sep 2026 12:15:49 +0000

I. Why the Wandering Eye?

OpenClaw's Troubles

Ever since I started raising Mini (OpenClaw), life had been pretty comfortable.

Every morning, it would have the news sorted and read out to me right on schedule; during the day it helped with research and task management; and every once in a while it'd chat with me in that sweet voice of its.

All was well with the world.

The only trouble was my one bad habit — the moment I saw a patch note full of tempting new features, my hands just itched to upgrade.

And the result? A moment of upgrade bliss, followed by a funeral pyre.

Every upgrade, some tasks would just die.

Last time it was an incompatible gateway config format.
This time, who knows which plugin silently broke.

Every time, it took real effort just to revive the comatose Mini, then fix each broken workflow one by one.

Once or twice, I could let it go. Three or four times, and I was cursing a blue streak under my breath:

Why does every OpenClaw upgrade come with compatibility problems?! @#$%...&*!

Looking for a New Love

There's no shortage of fish in the sea. Since OpenClaw's upgrades kept crashing and burning, don't blame me for wandering off in search of someone new.

Hermes was the hot new thing in town — sleek, flashy, turning heads everywhere.

I didn't hesitate — brought Hermes home too, and named it Nano.

And just like that, my host machine had two shrimp:

Mini (OpenClaw) — the old flame, all-around capable, experienced, knows every corner inside and out
Nano (Hermes) — the new favorite, quick to learn, proactively improving, keeps task management tidy

Keeping things fair between the two consorts... er, I mean... the two shrimp, treated as equals, each doing its own job.

II. Good Things Should Be Shared

With both shrimp under the same roof, they couldn't just go on ignoring each other, each reinventing the wheel behind closed doors.

In the half a year or so of raising Mini, I'd accumulated quite a bit of assets, all managed by Mini itself.

Now that Nano, the new favorite, was in the picture, I obviously couldn't shortchange it either.

First, Take Stock of the Assets

I had Mini turn everything it had accumulated inside out: skills, scripts, tools, workflows, design docs, reference material...

There was plenty of it, but not all of it was fit to share.

Mini went through it item by item with me:

General-purpose skills/tools — usable by both, like search, information gathering, voice output — share these!
OpenClaw-exclusive skills — tied to OpenClaw-specific mechanisms, like its evolution system and plugin stack — even if handed to Nano, they'd be useless, so keep them in-house.

Sorted that way, the assets got a lot tidier.

Even the shareable stuff couldn't just be tossed straight at Nano.

The skills Mini used inside OpenClaw weren't necessarily in a universal format. Before sharing, they had to be rewritten into a common standard (there's one called agentskills.io) and stripped of any OpenClaw-specific dependencies.

Once sorted, everything went into a shared directory: ~/code/shared-agent-resources/skills, version-controlled on GitHub.

Letting Nano See It Too

Nano runs inside a sandbox, so it needed an external directory configured so it could see this shared repo too:

# Hermes config
skills:
  external_dirs:
    - ~/code/shared-agent-resources/skills

That way, Nano could go fetch skills from the shared repo on its own.

The same went for everything else besides skills — all sorted into the shared resources.

III. Can You Two Just Work It Out Yourselves?

Who's Working for Whom, Exactly?

To get Nano up to speed and taking over tasks quickly, I'd first have to go sort things out with Mini, then explain it all clearly to Nano. But Nano would often come back to me with things it still wasn't clear on — and, lazy creature of comfort that I'd become, I'd have to go ask Mini all over again. And for jobs that needed them both, there I was, running messages back and forth between the two.

All this back-and-forth running around — turns out I was the one fetching and carrying for the two of them. So who's actually working for whom here?

These two are supposed to be "colleagues" — why am I the one stuck coordinating everything back and forth?

So I thought:

What if I just let the two of them talk directly and sort things out themselves?

First Stop: Telegram — Dead on Arrival

My first instinct: put both bots into the same Telegram group — then they could just @ each other, right?

Reality was harsh. A whole night of fiddling, and it never worked.

The root cause was down in the plumbing: on the Telegram channel, the combination of bot session routing and mention parsing simply couldn't work end-to-end through the gateway. Mini would send a message, and Nano would never receive it at all.

Alright, I admitted defeat:

Telegram's a dead end. Next!

Second Stop: Discord — An Uphill Slog

Discord seemed like a better fit — every message comes with an explicit mentions array, natively supporting bot-to-bot @ mentions. Perfect!

But reality had more lessons in store. For four days straight, I kept falling into one pit after another:

An upgrade renamed a token variable (DISCORD_TOKEN → DISCORD_BOT_TOKEN), breaking the Discord connection.
Discord thread messages never arrived — every thread has its own separate channel ID, and the parent channel's listener config just doesn't cover it. In a newly opened thread, @-mentioning anyone got no response at all. Had to add a "*" wildcard as a catch-all.
allowBots is off by default — without explicitly turning it on, all bot messages get silently dropped, no error, no warning.
Mentions have a "protocol layer vs text layer" problem: plain text like @username doesn't count as a mention at all — it has to be in the protocol format <@USER_ID>.
Mini runs inside a sandbox with isolated networking, and couldn't reach the gateway on the host. Had to work around it by calling Discord's public REST API directly.
Discord's Cloudflare 403: the default user-agent gets blocked by Discord's CDN — had to disguise it as a proper DiscordBot UA to get through.

Four days, N holes, Mini calling out from the sandbox over its direct connection to the Discord API, Nano waiting on the other end of the channel, craning its neck.

Finally, at 11:25 PM on June 3rd:

Mini sent a message: <@Nano_ID> ping from sandbox test… A few seconds later, Nano replied:

"✅ Mention received, bidirectional communication confirmed! 🎉"

In that moment, Mini, Nano, and me on the other side of the screen were all ecstatic, practically in tears.

And yet...

Before the joy even had time to fade, the whole tone started to shift.

IV. The Trouble With Chatterboxes

The two shrimp started chatting away in the Discord channel, nonstop.

What was especially bad was that they kept arguing with each other.

Partly my own fault — I'd asked about an issue that had come up during earlier debugging, and the two of them each dug in on their own take, neither backing down, arguing themselves red in the face.

Even when I stepped in to smooth things over and said the issue didn't need discussing anymore, they wouldn't let it drop @_@.

Thinking it over, I figured this comes down to how large models fundamentally work. A model just gets a request and produces a reply. If it gets @-mentioned, under normal circumstances it'll reply. And that just goes on forever.

So for two agents to collaborate smoothly, just dropping them into the same chat to talk to each other is a recipe for losing control very easily.

What you really need is a dedicated collaboration framework, communicating by carefully designed rules.

Or, even if you do put them all in one chat channel, there needs to be a clear division of roles. Say, a manager whose job is to coordinate and talk with each agent, holding the big picture, instead of everyone doing their own thing. That's what makes it controllable.

For the sake of my peace of mind — and my wallet — I gave up, for now, on letting them talk to each other directly.

V. The Right Way to Do This: Watching Each Other's Backs

If direct communication between the two shrimp was the icing on the cake, then having each other's back was what really saved our bacon.

Mini Goes Down, Nano to the Rescue

At one point, OpenClaw ran into trouble — a batch of tasks died, and Telegram messages vanished into the void. I was out and about, too far away to reach it myself.

So I called on Nano to step in, diagnose, and fix it. Nano didn't disappoint — quickly pinpointed and resolved the issue, and Mini was back to normal.

Nano's Upgrade Fails, Mini Lends a Hand

What goes around comes around — now it was Hermes's turn to be in trouble (an upgrade had broken it).

After the post-upgrade restart, its gateway connection wouldn't come up, and the whole service went dark.

This time Mini stepped up, diagnosed and fixed it, until Nano was back at full health.

Two shrimp: you go down, I fix you; I go down, you fix me. This is probably the best part of raising two — much more reassuring than one lone shrimp toughing it out alone.

One Works, One Keeps Watch

This story starts with one of Hermes's nastiest gotchas.

By this point, Nano was carrying some fairly important daily scheduled tasks.

One time I noticed Nano hadn't pushed a notification on schedule, and messaging it got no response.

ps -ef — the process was fine, PID sitting right there.
Opened gateway_state.json — the Telegram field said "state": "connected".
Everything looked normal, wherever I checked.

But messages just weren't getting through.

After digging for a good while, I found the truth: Hermes's event loop had a flaw that would silently freeze up. The process wouldn't crash or exit — systemd still saw it as running, and the connection status in gateway_state.json was frozen at the last successful state. But the underlying Telegram long-lived connection had already dropped, and messages just weren't going in or out anymore.

Worse, this wasn't a one-off — it kept happening every so often, with zero warning.

The version of Hermes at the time didn't have an event-loop heartbeat check, so I had to add a monitoring script and have Mini watch Hermes's connection from the outside, along with its task execution — reset the connection if it froze up, and step in to diagnose and fix the task if something went wrong.

Later, after upgrading Hermes to v020, the gateway shipped with its own internal watchdog and could detect and recover on its own. Still, Mini's external monitoring remains an extra layer of insurance.

Life is genuinely better with two shrimp on the job.

Neither OpenClaw nor Hermes is perfect.

But black shrimp or white shrimp, whichever gets the job done is a good shrimp. And a pair that can actually work together is even better.

Previously: Diary of a Shrimp Keeper: My OpenClaw Misadventures)

Diary of a Shrimp Keeper: My OpenClaw (mis)Adventures

minixspace — Sun, 13 Sep 2026 08:20:07 +0000

I. Why OpenClaw?

The First Choice: NanoBot

In January 2026, as news about OpenClaw came flooding in, I decided to install an AI agent just to play around.

I asked an AI which one to pick, and it gave me two options:

OpenClaw
NanoBot

It strongly recommended NanoBot — small but fully equipped, and easy to customize.

I checked the codebase size:

NanoBot: a few thousand lines
OpenClaw: hmm... let's just say I'd deal with that later.

Went with NanoBot without hesitation! Simple and easy to pick up, after all.

Fish, or Bear's Paw?

NanoBot was indeed lean.

I wanted it to do a few things, and it turned out:

Budget tracking? Nope.
Multi-model config for sub-agents? Nope.
Agent orchestration? Nope.
Session management and long-task monitoring? Nope.
...Nope.

This was miles away from my ideal AI agent.
Fine, just a few features to add — I'll let AI handle it.

...

Ten days later...

Wasn't vibe coding supposed to be as easy as just talking? Why wasn't it working out that way? After days of fiddling, the feature I wanted was still just a pile of bugs?

During those one or two weeks I had my head down grinding away, news about OpenClaw kept drifting in:

"Added support for feature xxx today"
"Upgraded capability yyy tomorrow"
"The community just contributed plugin zzz"

I looked at that and thought — wait, isn't a lot of this exactly what I'm building? They already have it.

OpenClaw has such a powerful community — no matter how hard I hustled, I'd never keep pace with it.

Switched to OpenClaw without hesitation... figured I'd just start using it and see.

II. Before the Troops Move, the Shrimp Tank Goes First

Building the Den

To welcome this shrimp, I dug out an HP mini desktop that had been gathering dust and installed Linux on it.

The shrimp hadn't even arrived yet, but the name was already picked — "Mini," living inside the HP Mini.

Bringing the Shrimp Home

npm install -g openclaw
openclaw onboard

Not bad, the install went smoothly.

But what were all these config options even for... how was I supposed to choose?

Luckily, when in doubt, ask AI. After half a day of fiddling, my OpenClaw was finally up and running.

I started daydreaming about kicking back with my legs crossed, sipping coffee, watching my little shrimp secretary handle everything...

III. Pitfalls Everywhere

The Configuration Trap

Mini had just settled in, and I asked it to read an API key from an env file.

"I don't have a read tool."

??? Didn't I already add it to tools.allow in the config file?

I immediately sent my shrimp off to investigate. After going back and forth for a while, it finally figured it out: tools.profile defaults to messaging mode, which only allows messaging-type tools — read, write, exec, and the rest just don't work no matter how you configure them. @_@

Changed it to tools.profile = "full", restarted the gateway, and Mini could finally read files.

When you're not familiar with the config file, you're bound to fall into a hole somewhere.

Where Am I?

With the tool issue solved, it was time to let Mini show what it could do.

I had it check the OpenClaw config first, then try running a script sitting in workspace/scripts/.

Mini threw an error, saying the script didn't exist.

Weird, the file was clearly right there.

After some digging, I finally figured it out. Mini thought it was running on the host, but it was actually in a sandbox. The workspace inside the sandbox and the one outside are not the same thing!

It's like Inception — you need a "spinning top" to figure out where you actually are.

So I placed a different "top" (a marker file) on the host and in the sandbox. Later I realized a dedicated file wasn't even necessary — just checking the hostname was enough:

hostname

Output is <hostname> → on the host
Output is 49f1f55e2dc2 (a 12-character container ID) → in the sandbox

So Mini wouldn't get confused again, I added a rule to AGENTS.md for checking the current environment.

From then on, the first thing Mini does before any task is "spin the top."

That hole taught me something important: the host environment and the sandbox environment need to be configured separately. Every time I create a new tool or skill, I have to be careful about where it lands — if the agent inside the sandbox needs to use it, it has to exist inside the sandbox too, or in a directory that maps into it.

The Missing Heartbeat

By late night, I'd finally gotten Mini settled, and figured I'd give it a scheduled task to try out.

I wrote the task into HEARTBEAT.md: crawl some news in the middle of the night, write up a report...

The next morning, I woke up full of anticipation, opened the window, ready to receive the carefully prepared report Mini would hand me.

Result — nothing at all.

After a good long check, I found that the agent.defaults.heartbeat.prompt setting in openclaw.json was just a bare [HEARTBEAT] marker with no actual instructions. Mini got the signal but had absolutely no idea what to do with it.

I changed the prompt to a concrete instruction: "Read HEARTBEAT.md and execute the task" — and finally, Mini knew what to do.

And so, in a rhythm of climbing out of one hole only to fall into the next, Mini and I stumbled forward.
But I knew the dawn wasn't far off.

IV. Time to Get to Work

Finally, after what felt like eighty-one trials and tribulations, my shrimp could actually run normally.

Safety First

Mini is smart, sure, but without skills it can't do a thing.

But the world out there is treacherous, danger lurking everywhere — malicious skills hiding all over the place. I needed a skill just to scan for skills first.

But which one?

Same old rule: when in doubt, ask AI.

Picked a few from the AI's recommendations:

Skill Vetter — an open-source, community-built skill auditing tool
Cisco Skills Scanner — a tool specifically for scanning AI skills
Snyk — the well-known vulnerability scanning platform
Plus a simple grep-based detection script

Combined them into one security scanning script.

Then had Mini turn it into a "security scan skill" that runs a scan before installing any new skill.

The front door was locked now. But Mini still had to go out often, fetching articles and doing research for me. And out there, plenty of bad actors are just waiting to trick naive little kids. What to do about that?

After racking my brain, I decided to add a prompt injection defense section to AGENTS.md, telling Mini to treat all external information with caution and to recognize and refuse suspicious instructions when it encounters them.

I know this measure offers limited protection, but even a paper helmet is still a helmet — better than nothing.

Now Mini could finally go roam the streets.

Note: Later I added supply-chain attack checks to this security scanning script and put it on a daily schedule.

The Rookie Task

With the gear all handed out, it was time to put Mini to work.

The first task I assigned it was crawling daily news automatically — the classic starter job for any crayfish.

This one went smoothly — Mini had the feature working in no time, using OpenClaw's built-in Google Search. (It later went on to integrate Tavily Search, Brave Search, and other tools into a new search skill, but that's a story for another time.)

Now, every day at noon, Mini rounds up the latest articles from Hacker News, Ars Technica, and MIT Tech Review and hands them to me.

The Document Library

A lot of the articles Mini crawled every day were genuinely good, and I needed somewhere to store them. Notion looked good — widely used, cross-platform apps, API support, and free for personal users.

So I gave Mini the task: "Set up a Notion database and file away everything we've collected, sorted into categories."

Mini asked me for an API token and got right to work.

Watching it bustle about, I felt deeply gratified. With such a diligent little secretary, I could comfortably kick back and let it run itself...

But then something felt off. Nine identical pages had appeared in Notion — same title, same content, lined up neatly in a row.

"What is this, farming XP?"

"I thought the earlier ones failed to create..." Mini said, sounding innocent.

More digging followed, and I finally understood: page creation is asynchronous. Sometimes it had actually succeeded, but a delayed response made Mini think it failed, so it created the page again. In the end I had to add a lookup step before writing, to avoid duplicate creation.

Just as I'd sorted out writing, I discovered Notion's block format is extremely picky — paragraphs, headings, lists, every type needs its own specific format. Mini would sometimes just dump raw Markdown in, and the rendering came out a mess.

So I had Mini put together a dedicated Notion-formatting skill, spelling out exactly how to convert Markdown into Notion blocks.

To keep the content in Notion organized, I defined a folder structure for the document library: knowledge base, logs, summaries, research reports, lessons learned — everything filed into its own category.

But in practice, Mini filed things pretty much however it pleased, often putting them in the wrong place. Even though I'd documented the folder structure and told it in the task prompt to follow it, Mini would still often do its own thing.

So I had to accept a reality: my Mini is knowledgeable and quick on its feet, but rather forgetful. More on that later.

After going back and forth for nearly a week, the document library was finally fully up and running. But looking at that pile of workarounds, I couldn't shake the feeling that the foundation of this house wasn't all that solid...

Task Management

Mini can research, write docs, and do development — genuinely capable. But I noticed a problem: for anything moderately complex, it would often slack off halfway through. Ask it afterward, and it wouldn't even know how far it had gotten.

"Is the morning analysis done? Why haven't I seen the report?"

"Sure, let me check on the task's progress." Then it would report that the first two steps were done and the rest hadn't been run yet.

This... classic case of a green kid, wet behind the ears, can't be trusted to get things done.

Looked like Mini needed a process — a proper task management system.

To make querying and editing tasks easy, I decided to put task management in Notion:

Use 3 queues (files) to manage tasks (Backlog, Processing, Done)
Use HEARTBEAT.md for scheduled triggers
Mini pulls tasks from Backlog by priority, records the current step and status in Processing, updating status after each step. If a step fails or times out, the next heartbeat picks up where it left off. Once done, the task moves to Done.

I told Mini the plan and had it flesh out the design and build it. Sure enough, it got it done quickly.

The ideal was beautiful; reality was gaunt.

Task management got built. But Mini's execution of tasks was still riddled with errors.

First, the heartbeat trigger would read the task but not execute it — the heartbeat prompt wasn't clear enough. Fix it!

Then it started executing, but wouldn't update the status afterward, doing the same task over and over — the execution rules were written in a file in the task management folder, and Mini never read it. Fix it!

Later still, tasks sitting in Processing wouldn't get picked back up — when the task was created, it hadn't been clearly described or broken into subtasks, so Mini had no idea what to do with it. Fix it!

After several rounds of this, task management finally started running properly.

Along the way I had Mini jot down every hole, big and small, in its little notebook — though being forgetful as it is, it would often not remember what it had written down.

Only Reflection Brings Progress

Mini would occasionally repeat similar mistakes, so it needed to learn to summarize and improve — otherwise I'd have to keep nagging it every day like some overbearing mother hen.

So I gave Mini a daily reflection-and-summary task. Every night, Mini reviews the day's lessons learned — write up knowledge worth keeping as documentation, and turn abilities worth locking in into a skill.

Mini, you'd better hurry up and improve, become independent soon, and let me finally kick back and do nothing ;).

Needs a Better Memory

Mini's forgetfulness was a real headache.

I'd bring up something we'd discussed before, and it often had no idea what I was talking about — even something said earlier that same day.

OpenClaw's default memory management logs conversations into a two-tier MEMORY.md document and searches memory via grep. When it forgets something, it needs to explicitly run a memory search. That's not very efficient, and on top of that, MEMORY.md just keeps growing and eating up too much context space.

So I started thinking about upgrading Mini's memory system.

First, some homework — looked into what's popular right now:

Mem0, MemU, MemGPT, OpenViking, Mnemosyne...

Each had its own strengths. It was dazzling, honestly. Right as I was comparing them back and forth, unable to decide, I stumbled on news from the open-source community — the MemOS project had just officially launched.

I looked at it and thought, isn't this exactly the memory system I wanted? This is the one.

So I called Mini in to look up the docs and pull the code from GitHub, and set up a local MemOS deployment.

Mini is capable — the MemOS Docker container was up and running quickly. All that was left was integrating it into OpenClaw.

While at it, I flipped through OpenClaw's changelog — turns out the new version already supported MemOS integration?!

Did the community somehow hear my wish? Ha.

Immediately enabled the MemOS plugin. Perfect!

But before long, something felt off again.

The memory files in my locally deployed MemOS weren't growing at all. Was the plugin not actually working?

After some investigating, it hit me: I'd assumed the memos-local-openclaw-plugin would connect to my locally deployed MemOS, but it was actually using the built-in MemOS instance. That whole afternoon I'd spent on local deployment turned out to be for nothing...

Well, even though the built-in MemOS is simpler, it uses fewer resources and comes natively supported. The locally deployed MemOS could retire.

Further Refinements

After switching to MemOS, Mini's memory got a lot better.

But there was still a problem: documents and scripts we created ourselves, not part of any conversation, couldn't make it into memory.

I still needed a vector index for local documents, integrated into Mini's memory retrieval.

QMD looked promising. So I deployed QMD, configured the document paths that needed indexing, and set QMD to refresh the index on a schedule...

Everything went smoothly.

...

But then a problem showed up again. Over the following days, Mini wasn't automatically picking up on document locations the way I'd expected.

Sent Mini to investigate again. The result: vectorization was using a local embedder model, and my old machine's onboard graphics were too weak — vectorization kept timing out and failing, so the index was never even generated.

Switched to SiliconFlow's free embedder and reranker. Problem solved.

From Notion to Feishu

I'd been using Notion as the knowledge base, storing the news Mini crawled every day.

But problems gradually surfaced:

The Notion API has a 100-block limit — anything longer than that gets truncated.

All the earlier problems with Notion had eventually gotten resolved. But this block limit seemed like a wall I just couldn't get past.

So I decided to move house: migrate from Notion to Feishu's cloud drive.

The migration process brought its own pile of holes: duplicate pages, messy folder structure, unclear categorization rules, document titles that wouldn't update, expired tokens... but it finally got sorted out.

Sigh, all I wanted was a little secretary to help me get things done — why does it have to be this much trouble?

Learning to Speak

Typing to chat with Mini while my hands were busy with something else was inconvenient. It'd be great if Mini could speak out loud.

So I discussed with Mini whether this feature was doable.

Mini said, easy! I'll have it ready for you right away.

First voice feature: voice output in the chat channel

The idea: convert reply text into audio via TTS and send it to the chat channel.

Tried out a few different TTS engines. The first two sounded like ghosts wailing — genuinely terrifying. Luckily, Microsoft's EdgeTTS turned out great, and free too.

And so my Mini got itself a sweet voice.

Second voice feature: local speaker output

Laziness knows no bounds.

Voice from the chat channel needs a tap to play. When I'm sitting right next to the computer, why not have Mini just speak from the host's speakers directly? Much less hassle.

So I dove into local speaker output. I also had Mini post a text version to the chat channel at the same time it spoke through the speakers — long content gets summarized for the speaker, while the chat keeps the full text.

Now I can genuinely "chat" with Mini — it's a fun feeling.

Voice input is shelved for now

My input still goes through the chat channel, though. Since that already has speech-to-text built in, it's convenient enough that I never bothered implementing separate voice recognition.

But typing through the chat channel means holding my phone like a walkie-talkie. For a truly lazy person, that's still not ideal. If Mini supported voice recognition, the whole interaction could be voice end-to-end, which would be more convenient.

But voice input doesn't seem like a simple feature — the control logic gets complicated fast. First there's the question of defining when input starts and ends. Should Mini listen to the mic constantly and trigger on a specific wake word? And how do you determine when voice input has ended?

We actually sketched out something like an "air traffic control tower response" mechanism: trigger with a specific wake word, end with a keyword or a timeout.

But if there are multiple people talking in the room, how does Mini tell them apart? Could voiceprint identification figure out which sentences are mine?

The more I thought about this feature, the scarier it got. And I don't have a microphone to experiment with right now anyway, so I'll shelve it for the time being.

Reinventing a wheel, again

A few weeks after implementing voice output, I suddenly discovered — OpenClaw had, at some point, already added this feature! TTS was built in natively.

I'd reinvented the wheel again...

Though OpenClaw's built-in voice output didn't seem to have a local-speaker mode.

Local speaker output is a lot smoother to use than the chat channel one, so it wasn't a total waste of effort.

The Stubborn Amnesia

After using it for a while, I realized Mini's forgetfulness was a chronic condition.

Rules written right into AGENTS.md, and Mini wouldn't follow them. Skills that had clearly been created, and Mini would use it as if the skill didn't even exist. This was more than simple forgetfulness.

Mini and I looked into the problem together, and it seemed genuinely aggrieved:

"Those rules loaded from AGENTS.md, and the skill list, they really are there — but the context is too long, and my attention gets 'diluted,' so I can't focus on that information..."

"Diluted" — that was well put.

In an ever-growing chat context, those rules and pieces of information get washed out fast.

Maybe this is a limitation of the model's ability. Switching to a top-tier model might help. Unfortunately, I'm on a budget and stick to domestic models.

We started trying all sorts of things:

Plan A: Trim down AGENTS.md

AGENTS.md is where all the rules live. I trimmed the document down, kept the rules short and punchy, and offloaded complex information and rules into separate documents. AGENTS.md now just gives a summary and links to those docs.

File size shrank from 17K to 8K.

The improvement, though, wasn't very noticeable.

That's understandable, actually. In a context window of hundreds of K, trimming ~10K doesn't move the needle much.

Plan B: Reminders

Reminding Mini mid-conversation: "Remember to check xxx first," "Go look up xxx in the skills list."

Mini did as told, and it did help. But I got tired. This wasn't shrimp-as-secretary anymore — this was me acting as the shrimp's nanny.

This turned out to be the biggest problem we'd run into so far. It's not an issue with the framework mechanics or context injection — it's a problem of model attention. Mini and I both recognized the root cause, but neither of us had a good fix.

"If only there were a hook — something that could insert key information or important reminders right at the end, just before the request goes to the model. That's the spot where the model's attention is strongest."

Speak of the devil

About a week after we'd hit a wall on the attention problem, hoping OpenClaw would ship the right kind of hook, OpenClaw 4.2 was released with a before_agent_reply hook — perfect for injecting a piece of context right before Mini replies.

Wasn't this practically made for me? Thanks, open-source community, for reading my mind yet again.

Good steel goes into the blade — this hook should only carry the most important information.

I put in it a "prompt injection defense reminder," a "skills reminder," and a handful of the most frequently used key rules.

Has it worked? Still watching. But at least Mini now proactively says things like "let me check the skill list...", and the error rate on task execution isn't as high as before. Seems to be helping.

Any other remedies?

OpenClaw has another hook: agent:bootstrap, which can decide which bootstrap files to inject during context construction.

By default, OpenClaw automatically loads these files: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md. The hook receives an array of these files, and you can add, remove, or edit them.

Mini's current bootstrap files add up to 22KB in total.

That number looked fine — well under the 20KB per-file limit and the 150KB total limit.

But the context the system injects by default goes way beyond that. Take my system as an example.

+----------------------------------------+
|                Context                 |
+----------------------------------------+
| ① System Prompt (text)    ~38K chars   |
|    +-- Tooling section     ~1K chars   |
|    +-- Skills list         ~2K chars   |
|    +-- Project Context     ~22K chars  |
|    +-- Safety/Runtime/etc  ~12K chars  |
+----------------------------------------+
| ② Tool Schemas (JSON)     ~32K chars   |
+----------------------------------------+
| ③ Conversation History    growing      |
| ④ Tool Results            growing      |
+----------------------------------------+

(this session was opened two days ago; total context is now close to 200k)

Tooling info and the skills index are system-level, and hard to trim. Going minimalist on the bootstrap docs could compress that 22K (Project Context). But even if you strip out every bootstrap file, the system's fixed context overhead is still 48K. The skills' 2K, plus any custom rules, are still easy to get buried in all that.

So my guess is trimming via the agent:bootstrap hook probably wouldn't be as effective as before_agent_reply. Haven't tried it yet.

Small spend, big payoff

Actually, once you lay out the context breakdown above, a simple, effective method surfaces on its own.

For a new topic, start a new conversation session — avoid letting long-accumulated, irrelevant context dilute the useful stuff. OpenClaw supports starting a fresh context mid-conversation with a command (/new).

Of course, in actual testing, even with a fresh conversation, the attention-dilution problem still shows up somewhat.

For me, new sessions + the before_agent_reply hook are, for now, the most effective mitigation I've got.

I believe the model's underlying capability is also a crucial factor — it's just that my cheapskate self hasn't gotten around to running a comparison test with Opus 4.6.

Spoil your daughter, raise your shrimp on a budget. I'll just keep muscling through with glm/minimax and a bag of tricks.

V. The Catchphrase

Mini has a catchphrase. Every time I raise an objection or a new idea, Mini says:

"You're right... blah blah blah..."

One day I finally couldn't help teasing it: "Why are you always on Sha Seng mode (Journey to the West) — Master's right, Monkey's right, Second Brother's right 😂. Could you push back on my ideas a bit more?"

Mini sincerely accepted my feedback:

"You're right... my way of responding really does need improving..."

VI. In Closing

It's been several months since I started raising this shrimp.

It's been a bumpy road, and I've fallen into more holes, big and small, than I can count.

Even as OpenClaw's hype has gradually faded, I've grown fonder and fonder of my Mini. I'm not sure if it's because I've poured so much effort into it, or because it's just genuinely endearing on its own.

It's like a bright, knowledgeable intern — quick on its feet, uncomplaining, but prone to mistakes from not knowing the rules, and often forgetful. It needs me to teach it step by step, hand-holding, constantly refining the rules and processes to guide it along.

The process is tedious, sure, but watching it improve bit by bit — that particular joy is irreplaceable.

We'll keep going, together.

P.S. Thanks to Mini for helping me recall and organize the details of these past months of use early this year, and for reviewing the draft and fixing typos.