@mrc2204/opencode-bridge

English README: README.en.md

opencode-bridge là cầu nối giữa OpenClaw và OpenCode theo hướng hybrid execution, callback orchestration và runtime control an toàn cho nhiều project.

Package này làm gì

Package này nối 2 phía runtime:

• OpenClaw side: routing theo project, run state, serve management, observability, callback policy
• OpenCode side: plugin callback bắt event terminal bên trong OpenCode runtime

Mục tiêu thực dụng:

• execution theo project rõ ràng
• callback quay về OpenClaw qua /hooks/agent
• artifact OpenCode-side cài được theo project hoặc global
• multi-project-safe boundary

Cài đặt

1) OpenClaw side

openclaw plugins install @mrc2204/openclaw-opencode-bridge

2) OpenCode side — cài theo project

npm run materialize:opencode-plugin:project

Project mode sẽ materialize plugin theo namespace clean:

• .opencode/plugins/openclaw-bridge/openclaw-bridge-callback.js
• .opencode/plugins/openclaw-bridge/config.json

và auto patch plugin entry trong .opencode/opencode.json thành:

{ "plugin": ["./plugins/openclaw-bridge/openclaw-bridge-callback.js"] }

3) OpenCode side — cài global

npm run materialize:opencode-plugin:global

Global mode sẽ materialize plugin theo namespace clean:

• ~/.config/opencode/plugins/openclaw-bridge/openclaw-bridge-callback.js
• ~/.config/opencode/plugins/openclaw-bridge/config.json

và auto patch ~/.config/opencode/opencode.json khi file này tồn tại thành plugin entry dạng:

{ "plugin": ["./plugins/openclaw-bridge/openclaw-bridge-callback.js"] }

4) Một lệnh cài

Project mode:

npm run install:bridge:project

Global mode:

npm run install:bridge:global

Environment callback tối thiểu

OpenCode-side callback plugin cần:

• OPENCLAW_HOOK_BASE_URL
• OPENCLAW_HOOK_TOKEN

Optional:

• OPENCLAW_BRIDGE_AUDIT_DIR
• OPENCLAW_BRIDGE_OPENCLAW_AUDIT_PATH

Mô hình runtime

Hybrid execution strategy

opencode-bridge hỗ trợ 2 lane thực dụng:

• CLI-direct: execution nhẹ cho task đơn giản
• serve/plugin mode: đường canonical cho callback, observability và event-driven lifecycle

Multi-project safety

Contract hiện tại giả định:

• 1 project = 1 OpenCode serve bind đúng repo
• chỉ reuse serve khi runtime introspection xác nhận đúng repo_root
• session tag phải giữ đủ callback identity theo run/session

Build và verify

npm install
npm run build
npm test -- --runInBand

Cấu trúc artifact

openclaw-opencode-bridge/
├── src/                 # OpenClaw-side runtime
├── opencode-plugin/     # canonical OpenCode-side plugin source
├── scripts/             # materialize/install helpers
├── dist/                # built artifacts
├── docs/                # install / architecture / contracts
└── skills/              # bridge-related skills/docs

Tài liệu liên quan

• docs/install/quick-start-2026-03-22.md
• docs/install/production-ish-install-2026-03-22.md
• docs/contracts/multi-project-contract-draft-2026-03-22.md
• docs/architecture/hybrid-execution-strategy-2026-03-22.md

Ghi chú: local debug/dev notes được tách khỏi README public-facing. Xem:

• docs/install/developer-local-debug-2026-03-22.md

Trạng thái

Hiện tại package đã ở mức functional + productized usable, với hardening/test/docs đã đi khá xa.