omo-claw

omo claw

SDK-only OpenClaw plugin and context-engine bridge for OpenCode + OmO

<a href="./README.zh-CN.md">简体中文</a> · <a href="./OPERATIONS.md">Operations</a> · <a href="./CONTRIBUTING.md">Contributing</a> · <a href="./SECURITY.md">Security</a>

omo claw connects OpenClaw threads to an isolated headless OpenCode + OmO runtime. It gives you a clean plugin entrypoint, a controlled bridge layer, replay-aware event reduction, permission flow management, and compatibility-aware operation without depending on ACP.

Install

Ask an agent to do it

Tell your OpenCode or OpenClaw agent:

Install and configure omo claw by following the instructions here:
https://raw.githubusercontent.com/Her-xanadu/omo-claw/main/docs/guide/install.md

Homebrew (macOS)

brew tap Her-xanadu/omo-claw https://github.com/Her-xanadu/omo-claw
brew install --HEAD omo-claw
omo-claw-install /path/to/your/openclaw/plugins/omo-claw

npm (GitHub-backed)

npm install -g github:Her-xanadu/omo-claw
omo-claw-install /path/to/your/openclaw/plugins/omo-claw

Git / source checkout

git clone https://github.com/Her-xanadu/omo-claw.git
cd omo-claw
./scripts/setup-local.sh

omo-claw-install clones the repository, runs local setup, and then prints the remaining OpenClaw registration steps.

---

Why this project exists

Most integrations stop at “call an SDK and hope it works.” omo claw goes further:

it isolates a dedicated headless opencode serve runtime
it maps OpenClaw threads into a session tree
it keeps permission flow, todo mirroring, summary reduction, and replay semantics in one bridge
it adds compatibility snapshots, diff classification, and mode switching so upgrades are survivable

This makes it useful both as a real plugin and as a reference implementation for building serious OpenClaw ↔ OpenCode bridges.

---

Architecture at a glance

Core layers

| Layer | Responsibilities | | --- | --- | | OpenClaw | Plugin host, context-engine registration, gateway status, user entry | | omo claw bridge core | Runtime management, SDK client, route engine, session graph, permission bridge, event reducer, replay, compatibility controller | | Headless OpenCode + OmO | Agent execution, event stream, todo source of truth, compaction, permission requests |

---

Highlights

Runtime & execution

isolated opencode serve runtime on port 19222
XDG-separated config / data / state
Basic Auth protected bridge runtime

Session intelligence

thread → root session mapping
command-first, agent-fallback routing
message correlation for promptAsync + SSE flow

Long-running task continuity

event reduction
summary cache
todo mirror
replay / rebind support
compaction-friendly companion hook path

Compatibility controls

capability snapshot collection
diff classification
mode switching (full, compatible, safe, quarantine)
adapter registry plumbing

---

Prerequisites

Before using omo claw, make sure you have:

Bun
opencode CLI available in PATH (or at ~/.opencode/bin/opencode)
an OpenClaw installation that supports context-engine plugins
permission to run a local headless service on 127.0.0.1:19222

Supported operating systems

| OS | Status | Notes | | --- | --- | --- | | macOS | ✅ primary tested platform | recommended environment | | Linux | ⚠️ partially supported | only if your OpenClaw + OpenCode stack already works | | Windows | ❌ not documented | use at your own risk / not currently supported |

Required software

| Requirement | Why it is needed | | --- | --- | | Bun | install dependencies and run the TypeScript project scripts | | OpenCode CLI (opencode) | starts the isolated headless runtime | | OpenClaw | hosts the plugin / context-engine | | Local filesystem access | stores runtime config, state, and generated definitions |

Before you run setup

confirm bun --version works
confirm opencode --help works, or ~/.opencode/bin/opencode exists
confirm OpenClaw can load plugins from your plugin workspace
confirm port 19222 is available

> Homebrew and npm can bootstrap installation, but this repository is still an OpenClaw plugin project with a managed runtime bridge.

---

Run after install

./integration/bridge-runtime/bridge-launcher.sh
./tests/live/runtime-health.smoke.sh

If everything is wired correctly, the smoke check returns:

{"healthy": true, "version": "1.2.21"}

---

Install into OpenClaw

1. Place this repository into your OpenClaw plugin workspace. 2. Register openclaw.plugin.json with your OpenClaw installation. 3. Configure the context-engine slot to use plugin id omo-claw. 4. Start the bridge runtime with ./integration/bridge-runtime/bridge-launcher.sh. 5. Verify the runtime with ./tests/live/runtime-health.smoke.sh.

The main OpenClaw-facing identifiers are:

| Item | Value | | --- | --- | | Plugin id | omo-claw | | Plugin name | omo claw | | Gateway method | omo-claw.status | | Status command | omo_claw_status |

---

Local development

./scripts/setup-local.sh
bun test
bun run typecheck
./tests/live/runtime-health.smoke.sh

Useful extra commands:

bun run compile:definitions
./scripts/publish-github.sh omo-claw Her-xanadu public

---

Repository layout

| Path | Purpose | | --- | --- | | src/ | bridge implementation | | integration/bridge-runtime/ | isolated runtime wrapper, config, launcher | | definitions/ | single-source IR, compiler, generated manifests | | compatibility/ | snapshots, diff classifier, adapter registry | | contracts/ | machine-checkable bridge contracts | | tests/ | unit, contract, e2e, smoke verification | | Formula/ | Homebrew formula for the installer wrapper | | docs/guide/ | agent-friendly install guides | | docs/assets/ | README visual assets |

---

Security notes

never commit integration/bridge-runtime/.bridge-secret
keep runtime state under ignored integration/bridge-runtime/xdg/
review generated artifacts before publishing if local metadata changes
validate compatibility mode and event-directory filtering after upgrades

---

Documentation

---

Contributors

OpenClaw for the plugin host and context-engine surface
OpenCode for the SDK/runtime model that powers the bridge

---

License

MIT

Summary

Install to Claude Code