Repository navigation
OpenClaw cannot reach the OpenCode server: build all three dispatch mechanisms (ACP-runtime agent, headless sessions_spawn, opencode-route provider front) #2229
Description
Problem
OpenClaw cannot run jobs carried by the OpenCode workhorse route (opencode-route/workhorse). Established in the OpenClaw-vs-OpenCode 1v1 round 2 (see #2171, comment 6493787758):
openclaw agent --model opencode-route/workhorse→Unknown model. OpenClaw's only providers are four local OpenAI-compatible proxies —agy(:18743),codex-proxy(:18744),design-code(:18746),commandcode(:18748) — and none fronts the OpenCode server. OpenCode's server speaks its own session API, not the chat-completions shape OpenClaw providers use.- ACP spawn tooling (
sessions_spawnwith runtimeacp) is exposed only to non-sandboxed chat-channel sessions; both headless surfaces (CLI agent, embedded exec) run a restricted tool catalog without it. The ACP plumbing itself is healthy (backend acpx, dispatch enabled,opencodeallowed; merged PR openclaw: enable claude, codex, agy as ACP agents alongside opencode #1728 widens allowedAgents but does not change the dispatch surface). - Result: round 2 of the 1v1 ran zero fixtures; OpenClaw's harness and its Command Code door cannot be varied independently, so the door-vs-platform question stays open.
Direction (Drew, 2026-10-29)
Build all three mechanisms — not a menu. Sequenced most-straightforward first:
- ACP-runtime agent in
home/openclaw/default.nix: anagents.list[]entry withruntime.type="acp",runtime.acp.agent="opencode"→openclaw agent --agent <id>dispatches turns to the OpenCode harness as a standing capability, model settable per run. - Expose
sessions_spawnto headless/CLI sessions (tool-profile change). Determine whether this isdefault.nixconfig or requires patching upstream OpenClaw source; if source, build it as the fleet's packaging patch and say so plainly here. - opencode-route provider front: a small local proxy (mirroring the commandcode proxy's pattern, next fixed port per the Local proxy discovery: port files, sockets, or a registry instead of fixed ports? #437 convention) exposing
opencode-route/*models in chat-completions shape, backed by the laptop OpenCode server (:13420, default model already the workhorse route), plus themodels.providersentry inhome/openclaw/default.nix— so--model opencode-route/workhorseworks directly.
Acceptance
- Each mechanism lands as its own commit/PR under repo rules and is tracked here.
- Each mechanism is proven live where it allows: an actual OpenClaw run carried by
opencode-route/workhorse, verified from the OpenCode DB v2 tables (session_v2/session_message) — the route record, not the request label. - If a mechanism proves impossible, its precise technical blocker is documented here and the others continue.
Cross-refs: #2171 (comparison program), #437 (fixed ports), #2170 (topology).
Acceptance criteria
- At least one of the three dispatch mechanisms (ACP-runtime agent, headless
sessions_spawn, opencode-route provider front) demonstrably runs an OpenClaw job on theopencode-route/workhorseroute end-to-end, with the run evidence linked here — and the issue's goal is all three, each either working or closed with a named blocker. - For each mechanism that cannot work, the specific blocking constraint (tool-catalog restriction, provider shape, config surface) is recorded on this issue so the 1v1 comparison (OpenClaw: finish setup, begin passing jobs, and review results against OpenCode #2171) can cite it.
- The OpenClaw-vs-OpenCode comparison can vary door and harness independently for at least the working mechanism(s): a fixture run through OpenClaw lands on the OpenCode server and is visible in its session store.
Activity
developing-today commentedon Oct 29, 2026
CODE-1101
dezren39 commentedon Oct 29, 2026
Determinations from the code (2026-10-29)
M1 schema (confirmed in shipped docs,
docs/tools/acp-agents/bindings.md):agents.entries.*.runtime.type="acp"withruntime.acp.{agent,backend,mode,cwd}. The fleet config renders agents as anentriesmap, so the entry lands asagents.entries.opencode-acp.M2 is a packaging patch, not config (stating plainly per the issue): in the pinned OpenClaw 2026.10.7 dist,
createSessionsSpawnToolis gated by!embedded || options?.allowGatewaySubagentBinding === true.isEmbeddedMode()is a process-local flag set by the CLI entry point;allowGatewaySubagentBindingis passed only by gateway/channel-side runners. No config key (tool profile included) feeds either. The fleet fix patches the pinned package in the flake so embedded CLI runs also create the spawn tool; the patch asserts its pattern at build time so an upstream change fails loudly instead of silently reverting.M3 seam: new
bin/opencode-route-proxy.mjs(node, mirroringcommandcode-proxy.mjs's HTTP surface +proxy-port.mjsparsing), port 18750 (next after claude-code 18749 in the #437 block), backed by the OpenCode server v2 API on 127.0.0.1:13420:POST /api/session(model set at creation) →POST /api/session/{id}/prompt→POST /api/experimental/session/{id}/wait→GET /api/session/{id}/message. Verified live 2026-10-29: a workhorse session completed and its assistant message recorded the pool door it drew (opencode-go.lab/deepseek-v4.1-flash#high). Server password read from~/.local/state/opencode/service-prod.jsonat runtime, never committed. Provider entry via the existinglocalProviderhelper inhome/openclaw/default.nix; proxy enrolled with the proxy-supervisor + a systemd user unit inhome/common/default.nix, mirroring commandcode.feat(openclaw): add opencode-acp ACP-runtime agent (#2229)
dezren39 commentedon Oct 29, 2026
Intake review
priority/high. Normalized:kind/feature,status/needs-triage,effort/l,meta/enriched; AC appended.feat(openclaw): opencode-route provider proxy — OpenAI-compatible fro…
dezren39 commentedon Oct 29, 2026
Method 3 (provider front) — BUILT + LIVE-PROVEN ✅ (priority target per Drew)
PR: #2250 — opencode-route provider proxy on fixed port 18750.
Seam: a small node proxy mirroring the commandcode proxy pattern (
bin/opencode-route-proxy.mjs), exposing opencode-route/* pools in the chat-completions shape, backed by the OpenCode server v2 session API. The in-server endpoint alternative was larger; the proxy follows the established #437 fleet pattern.Live proof (2026-10-29):
openclaw agent --local --model opencode-route/workhorse→ repliedOC-ROUTE-OK; run meta provider=opencode-route, model=workhorse, fallbackUsed=false.ses_e5e78b6f4f4ffeVyPSZquFZkwVtitled "opencode-route-proxy: workhorse"; assistant message carried by providerIDopencode-go, modeldeepseek-v4.1-flash, varianthigh(the workhorse pool door); session idle-complete.Permanent at the next switch (proxy-supervisor takes port 18750 from the checkout; gateway gains the provider entry + After/Wants). Methods 1 (ACP-runtime agent, PR #2237 already open) and 2 (sessions_spawn packaging patch) proceed next, in that order.
dezren39 commentedon Oct 29, 2026
Scope final (Drew, 2026-10-29)
Method 3 (opencode-route provider front) was the priority build and is done: PR #2250, live-proven (details in the method-3 comment above).
Methods 1 and 2 are descoped to follow-ups — not built in this pass:
opencode-acp) → Follow-up (#2229): ACP-runtime agent entry for OpenClaw→OpenCode dispatch (opencode-acp) #2256. PR feat(openclaw): opencode-acp ACP-runtime agent (#2229 mechanism 1) #2237 already holds the schema-verified entry as a starting point; its live spawn proof depends on method 2's surface.gatewayPath.Trigger for both: sometime soon / when an OpenClaw-origin workload needs them.
dezren39 commentedon Oct 30, 2026
Deploy chain complete — closing the loop on this build issue.
The switch landed 2026-10-30 ~06:29 CDT: generation 515 (from frozen tree at c32be58). PR #2250 is merged and the opencode-route provider is live via this switch; all Codex findings on the chain PRs were dispositioned during the merge-everything pass.
Activated with this switch: pm-apps #1762, ACP agents #1728, Spark round-robin #2184, Gemini burn #2200, defaults #2198 (default model verified:
opencode-route/workhorse), codex-connectors #2068, Qwen/codedb parks + messaging-embedding off #2220 (llama-server count 0; codedb verified in disabledMcpServers), opencode-route provider #2250 (route proxy answering on 18750; provider present in OpenClaw's rendered config).Verification (on the laptop, post-activation): ports 8484 (Grist), 7777 (Pad), 6056, 4870, 18789 (gateway), 13420 (OpenCode), 18750 (route proxy) all answering; exactly one opencode serve process; OpenChamber up on its durable Nix unit. One non-core exception: Kaneo (5173) — the container is up but its API process is not yet listening (entrypoint waiting, healthcheck failing); tracked with the pm-stack work, no rollback taken for it.
The road here, for the record: the switch was blocked in turn by the summarize-pnpm-deps hash (#2669), then by mcpx's sandbox check phase — five suites excluded interim via the package's own checkExclude mechanism (#2686, PRs #2687/#2707/#2710; all five still run in CI on main) — and finally by four hand-placed user unit files blocking Home Manager activation, moved aside to ~/backups/hm-clobber-2026-10-30/ on the laptop.