OneClaw Runtime Channel

@oneclaw-plugins/channel connects an isolated OpenClaw Runtime to the OneClaw API as the oneclaw direct-message channel.

The Runtime initiates one authenticated WebSocket connection. OneClaw API commands enter a transactional SQLite/WAL Inbox, execute through OpenClaw, and produce Protocol v1 events through a reliable Outbox. Apps never connect directly to this plugin.

Compatibility

| Component | Fixed version | | ----------------- | --------------------------- | | Channel package | 0.1.26 | | Runtime Events | 0.1.3 | | Native Task APIs | OpenClaw 2026.7.1-2+ | | Protocol contract | 1.0.0 / wire version 1 | | OpenClaw | 2026.7.1 | | Node.js | 24.15.0 production and CI | | Runtime image | exact-version npm packages |

The Channel and Runtime Events packages are one release unit. Always build their tarballs from the same revision; the Channel uses the shared SDK's active-Run and Attention context exports, so mixing an older Runtime Events tarball with a newer Channel tarball is unsupported even when the package version strings match.

The first release intentionally provides at-least-once execution. A narrow Runtime crash window can create a duplicate internal top-level Run. Public command, Run, message, and event IDs remain stable; projections and results are idempotent. Ambiguous high-side-effect work enters recovery_unknown and waits for user confirmation instead of retrying silently.

The plugin marks publish, payment, deletion, external-write, and unknown third-party tools through OpenClaw's public before_tool_call hook. A matching after_tool_call records the known return, while the Run remains conservatively classified as high-side-effect for crash recovery. The API receives a durable run.updated snapshot with wire status waiting and a recovery_unknown summary; read-only and tool-free work continues to recover automatically.

Task Dock snapshots use core-owned Runtime state on OpenClaw 2026.7.1-2 and newer. Session Goal, TaskFlow, and standalone Task Run are normalized into one business snapshot shape before entering the durable Outbox; API storage keeps that JSON shape while client APIs expose one stable Task DTO. On OneClaw direct sessions, the first structured update_plan or mutating native Workboard operation atomically establishes a missing Goal from the current user request. Goal-labeled Workboard cards and their linked descendants are projected alongside native Plan steps, including bounded completion details, without exposing internal workboard_* tool plumbing. Task reporting has no dependency on the removed oneclaw-workflows plugin or its oneclaw.tasks.get method. Ordinary replies without any native task authority never fabricate a Task. Completion summaries exposed as authoritative workItems[].detail are preserved as steps[].detail; a terminal Run still cannot terminalize a non-terminal Runtime Task.

Environment

ONECLAW_CHANNEL_ENABLED=true
ONECLAW_API_URL=https://api.example.com/api/v1
ONECLAW_RUNTIME_ID=runtime_...
ONECLAW_INSTANCE_SECRET=...
ONECLAW_CHANNEL_STATE_DIR=/data/oneclaw-channel

The instance secret is read once during startup and immediately removed from process.env, so Agent-spawned child processes cannot inherit it. It is sent only in Runtime-authenticated HTTP/WebSocket Authorization headers and never in a JSON frame. The plugin derives the frozen /api/v1/runtime/channel WebSocket endpoint from the API base URL.

Missing configuration leaves the channel disabled or unconfigured without preventing the OpenClaw Gateway from starting.

Contract and development

The canonical shared contract is in contracts/.

corepack pnpm install --frozen-lockfile
pnpm contract:validate
pnpm typecheck
pnpm test
pnpm build

The durable Echo and fault-injection record is documented in E0_D0_IMPLEMENTATION.md.

Attribution

Upstream provenance and the original MIT terms are preserved in NOTICE and LICENSE.