Techcle Wiki

README

4 min read

OpenClaw → OpenCode Bridge

Project: OpenClaw-OpenCode Integration via ACP
Status: Planning
Created: 2026-02-12

Overview

Enable OpenClaw to control OpenCode agents via the Agent Client Protocol (ACP), allowing users to:

  • Start/manage OpenCode sessions from WhatsApp/other messaging surfaces
  • Monitor long-running coding tasks remotely
  • Interact with OpenCode agents without a terminal/web UI

Problem Statement

OpenCode is a powerful AI coding agent that runs as:

  1. CLI: One-shot tasks via opencode run "prompt"
  2. TUI: Interactive terminal UI (default mode)
  3. Web UI: Browser-based interface (opencode web)
  4. Daemon: Headless server (opencode serve / opencode acp)

Current OpenClaw integration (via coding-agent skill) only uses CLI mode — spawning short-lived processes. This works for quick tasks but lacks:

  • Persistent sessions: Can’t resume long-running work
  • Remote control: Need terminal access to check status
  • Multi-session management: Hard to coordinate multiple agents
  • Real-time updates: No streaming of agent progress

Solution

Build an ACP client tool for OpenClaw that enables protocol-level integration:

User (WhatsApp) → OpenClaw → ACP Protocol → OpenCode Daemon
                                              ↓
                                         Agent Sessions

Key Capabilities

  1. Session Management

    • Create new OpenCode sessions with project context
    • List active/paused sessions
    • Resume existing sessions
    • Terminate sessions

  2. Message Interaction

    • Send prompts/instructions to agents
    • Stream responses back to user
    • Handle multi-turn conversations

  3. Status Monitoring

    • Check agent progress (files changed, tests run, etc.)
    • Get token usage / cost stats
    • Export session history

  4. Permission Handling

    • Relay permission requests to user via OpenClaw
    • Forward approvals/denials back to agent

Architecture

Components

  1. OpenCode Daemon (opencode acp or opencode web)

    • Runs as persistent service (local or remote)
    • Exposes ACP endpoints (HTTP + WebSocket)

  2. OpenClaw ACP Client Tool (new)

    • Speaks ACP protocol
    • Manages connection lifecycle
    • Translates user intent → ACP calls

  3. Updated coding-agent Skill (enhanced)

    • Detects if ACP server is available
    • Uses ACP when possible, falls back to CLI
    • Provides unified interface regardless of mode

Connection Modes

Local: OpenCode daemon on same machine as OpenClaw

opencode acp --port 3333
# OpenClaw connects to localhost:3333

Remote: OpenCode on separate container/VPS

opencode acp --hostname 0.0.0.0 --port 3333
# OpenClaw connects to remote-host:3333

Multi-Instance: Multiple OpenCode daemons for parallel work

# Dev projects
opencode acp --port 3333 --cwd ~/dev-projects
 
# Ops projects  
opencode acp --port 3334 --cwd ~/ops-projects

User Experience

Example: Start coding task from WhatsApp

User: "Start OpenCode on my api-server repo and add rate limiting to the /login endpoint"

OpenClaw:
1. Checks if ACP server is running
2. Creates new session: project=~/projects/api-server
3. Sends prompt to agent
4. Streams progress updates to WhatsApp
5. Notifies when complete with summary

User can:
- Check status: "What's OpenCode doing?"
- Intervene: "Stop and show me the changes"
- Resume later: "Continue the rate-limiting work"

Example: Monitor multiple agents

User: "Start OpenCode on these 3 bugs in parallel"

OpenClaw:
1. Creates 3 sessions (one per bug)
2. Tracks all in background
3. Sends updates as each completes
4. Aggregates results

User: "Show me session status"
OpenClaw: Lists all 3 sessions with progress

Technical Approach

Phase 1: Discovery

  • Document ACP protocol (HTTP routes, WebSocket events)
  • Test opencode web vs opencode acp capabilities
  • Identify minimum viable feature set

Phase 2: Core Client

  • Build ACP client library (TypeScript or similar)
  • Implement session create/list/resume
  • Implement message send/receive
  • Handle WebSocket streaming

Phase 3: OpenClaw Integration

  • Create opencode tool for OpenClaw
  • Wire into agent message handling
  • Add WhatsApp-specific formatting for responses

Phase 4: Enhancements

  • Permission approval flow via messaging
  • Multi-instance support (connect to multiple daemons)
  • Auto-reconnection / resilience
  • Session export/import for portability

<<<<<<< HEAD

  • OpenCode Bridge Plugin: /workspace/projects/ai-dev/plugins/opencode-bridge/
    • OpenCode → OpenClaw direction (permission approvals)
    • Provides reference for WebSocket patterns
  • coding-agent Skill: /app/skills/coding-agent/SKILL.md =======
  • OpenCode Bridge Plugin: projects/ai-dev/plugins/opencode-bridge/ (if it exists)
    • OpenCode → OpenClaw direction (permission approvals)
    • Provides reference for WebSocket patterns
  • coding-agent Skill: app/skills/coding-agent/SKILL.md (relative to OpenClaw root)

f146a548fbab991798ce91719b88cbf1f064588a

  • Current CLI-based integration
  • Will be enhanced to use ACP when available

Next Steps

  1. Document ACP protocol — understand endpoints, auth, WebSocket events
  2. Proof of concept — manual curl/wscat interaction with opencode acp
  3. Design tool interface — what functions does OpenClaw need?
  4. Implement MVP — session create + send message + get status

Files in This Project

  • README.md — This overview
  • prd.md — Product requirements and use cases
  • architecture.md — Technical design and implementation details
  • builder-pattern.md — WhatsApp group → OpenCode session workflow (sibling worktree pattern)
  • api-contract.md — OpenClaw tool interface spec
  • acp-protocol.md — ACP protocol documentation (to be written)

Graph View