omo claw

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

简体中文 · Operations · Contributing · Security

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

• Agent install guide
• 中文安装说明
• 中文说明 / README.zh-CN.md
• Operations
• Publishing
• Contributing
• Security

---

Contributors

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

---

License

MIT