Techcle Wiki

Prd

7 min read

Product Requirements: OpenClaw-OpenCode ACP Integration

Status: Draft
Author: OpenClaw Agent
Date: 2026-02-12

Vision

Enable seamless control of OpenCode AI coding agents from any OpenClaw messaging surface (WhatsApp, Telegram, Discord, etc.), turning mobile devices into powerful remote development interfaces.

Goals

  1. Remote Control: Start and manage OpenCode sessions without terminal access
  2. Persistent Work: Long-running coding tasks that survive connection drops
  3. Multi-Session: Coordinate multiple OpenCode agents in parallel
  4. Cross-Device: Start work on desktop, check status on phone, resume on laptop
  5. Team Collaboration: Share OpenCode instances for pair programming / code review

Non-Goals

  • UI Replacement: Not trying to replace OpenCode’s web UI — complement it
  • Custom Agent Logic: Use OpenCode as-is, don’t fork/modify the agent
  • Local-Only: Remote/distributed setups are first-class, not an afterthought

User Personas

1. Solo Developer (Primary)

  • Works on multiple projects simultaneously
  • Uses WhatsApp on phone to check/resume work
  • Wants agents running while AFK (meetings, commute, etc.)

2. Team Lead (Secondary)

  • Reviews PRs via OpenCode agents
  • Needs to monitor multiple agent sessions (one per PR)
  • Wants to approve permissions without switching contexts

3. DevOps Engineer (Tertiary)

  • Runs OpenCode on remote VPS for heavy builds
  • Controls via mobile when away from desk
  • Needs session persistence across SSH disconnects

Use Cases

UC-1: Create Dedicated OpenCode Group (Primary Flow)

Actor: Solo Developer / Team Lead
Trigger: New project needs AI coding assistance

Flow:

  1. User creates WhatsApp group: “API Team”
  2. Adds team members + OpenClaw bot <<<<<<< HEAD
  3. User (in group): “@OpenClaw start OpenCode session for /workspace/repos/ai-dev, use repos: ai-dev, domain-apis”
  4. OpenClaw:
    • Creates builder workspace at /workspace/.builders/api-team-abc123/ =======
  5. User (in group): “@OpenClaw start OpenCode session for repos/ai-dev, use repos: ai-dev, domain-apis”
  6. OpenClaw:
    • Creates builder workspace at .builders/api-team-abc123/

f146a548fbab991798ce91719b88cbf1f064588a

  • Uses Taskfile to create sibling worktrees (workspace-root, ai-dev, domain-apis)
  • Starts OpenCode ACP server in builder directory
  • Binds session to WhatsApp group (all messages routed, not just @mentions)
  • Responds with session details and URL
  1. Team members chat naturally: “Add rate limiting to /login endpoint”
  2. Every message goes to OpenCode agent (full conversation context)
  3. OpenCode streams progress back to group:
    • ”📂 Opened ai-dev/services/gateway/src/auth.ts”
    • “✏️ Added express-rate-limit middleware”
    • ”🧪 Running tests…”
    • ”✅ All tests passed!”
  4. OpenCode: “Done! Rate limiter added (5 req/min). Ready to commit?”
  5. Team member: “Yes, commit and push”
  6. OpenCode: ”✅ Committed to ai-dev/main, pushed”

Exit Criteria:

  • Builder workspace created with proper worktree structure
  • OpenCode session running and bound to group
  • All group messages route to agent
  • Team can chat naturally without @mentions
  • Progress updates visible to all group members

UC-1b: Admin Manages Sessions (via DM)

Actor: Admin (project owner)
Trigger: Need to view/manage multiple OpenCode sessions

Flow:

  1. User (DM to OpenClaw): “Show me all OpenCode sessions”
  2. OpenClaw lists all active sessions with group bindings: 
    📊 Active Sessions:

1. api-team-abc123
   Group: API Team (WhatsApp)
   Repos: ai-dev, domain-apis
   Status: Working on rate limiting

<<<<<<< HEAD Builder: /workspace/.builders/api-team-abc123

  Builder: .builders/api-team-abc123

f146a548fbab991798ce91719b88cbf1f064588a

  1. frontend-team-def456 Group: Frontend Team (WhatsApp) Repos: dashboard Status: Idle (15m) <<<<<<< HEAD Builder: /workspace/.builders/frontend-team-def456 ======= Builder: .builders/frontend-team-def456

f146a548fbab991798ce91719b88cbf1f064588a

3. User: "Pause frontend-team session"
4. OpenClaw pauses session, notifies Frontend Team group
5. User can later: "Resume frontend-team" or "Terminate api-team"

**Exit Criteria:**
- Admin can view all sessions across groups
- Can pause/resume/terminate from DM
- Affected groups notified of state changes

---

### UC-2: Check Status of Running Agent

**Actor:** Solo Developer  
**Trigger:** User checks in on long-running task

**Flow:**
1. User: "What's OpenCode doing?"
2. OpenClaw queries active sessions
3. Responds:

📊 OpenCode Status:

Session: api-server-ratelimit Status: Running Progress: Writing tests (3/5 complete) Files: 7 modified, 2 created Tokens: 12.5K used (~$0.08) Started: 23 minutes ago


**Exit Criteria:**
- User gets meaningful status without context-switching

---

### UC-3: Resume Paused Work

**Actor:** Solo Developer  
**Trigger:** User wants to continue yesterday's work

**Flow:**
1. User: "Resume the OpenCode session from yesterday"
2. OpenClaw lists recent sessions:

Recent Sessions:

  1. api-server-ratelimit (paused, 18h ago)
  2. dashboard-dark-mode (completed, 2d ago)
  3. fix-bug-234 (failed, 3d ago)
3. User: "Resume #1"
4. OpenClaw reconnects to session, shows last context:

Resuming api-server-ratelimit…

Last message: “Rate limiter added. Should I write integration tests?”

You can continue the conversation or give new instructions.

5. User: "Yes, write the tests"
6. Session continues

**Exit Criteria:**
- Sessions persist across disconnects
- Context is preserved (files open, conversation history, etc.)

---

### UC-4: Parallel PR Reviews

**Actor:** Team Lead  
**Trigger:** Multiple PRs need review

**Flow:**
1. User: "Review PRs #86, #87, #88 in parallel with OpenCode"
2. OpenClaw:
- Creates 3 sessions (one per PR)
- Clones repo to temp directories (or uses git worktrees)
- Starts OpenCode agent in each
3. Streams updates as reviews complete:

✅ PR #86 review done:

  • Code quality: Good
  • Security: 1 issue (SQL injection risk in query builder)
  • Recommendation: Request changes

⏳ PR #87 in progress… ⏳ PR #88 in progress…

4. User can ask follow-ups: "What's the SQL issue in #86?"
5. OpenClaw routes question to correct session

**Exit Criteria:**
- Multiple agents run in parallel without interference
- Results aggregated and delivered to user
- User can drill into specific sessions

---

### UC-5: Remote Server Setup

**Actor:** DevOps Engineer  
**Trigger:** Wants to run OpenCode on beefy VPS, control from laptop/phone

**Flow:**
1. User SSHs to VPS, starts daemon:
```bash
opencode acp --hostname 0.0.0.0 --port 3333 --cwd ~/projects
  1. In OpenClaw config, adds remote instance: 
    opencode:
  instances:
    - name: vps-heavy
      url: http://vps.example.com:3333
      default_cwd: ~/projects
  2. User (via WhatsApp): “Start OpenCode on vps-heavy and build the Docker images”
  3. OpenClaw connects to remote ACP server
  4. Creates session on VPS
  5. User gets updates on phone, VPS does the heavy lifting

Exit Criteria:

  • Supports remote ACP connections
  • Config-driven instance management
  • Sessions run independently of OpenClaw Gateway location

UC-6: Permission Approval via Messaging

Actor: Solo Developer
Trigger: OpenCode agent needs permission to run command

Flow:

  1. OpenCode agent encounters permission check: 
    Permission required:
Command: npm install express-rate-limit
Reason: Adding dependency to package.json
  2. Agent sends permission request to OpenClaw (via existing bridge plugin)
  3. OpenClaw forwards to user via WhatsApp: 
    🔒 OpenCode needs permission:

Session: api-server-ratelimit
Action: Install npm package
Command: npm install express-rate-limit

[Approve] [Deny] [Show More]
  4. User taps “Approve”
  5. OpenClaw sends approval back to agent
  6. Agent proceeds with installation

Exit Criteria:

  • Bidirectional communication: OpenCode → OpenClaw → User → OpenClaw → OpenCode
  • Inline approval buttons (where supported)
  • Fallback to text commands (“approve”, “deny”)

Requirements

Functional Requirements

IDRequirementPriorityNotes
FR-1Connect to local/remote ACP serverP0Core capability
FR-2Create new OpenCode sessionP0With project path, model, agent config
FR-3Send message to sessionP0Prompt/instruction from user
FR-4Receive session responsesP0Stream or poll
FR-5List active sessionsP0Show status, progress, metadata
FR-6Resume paused sessionP1Reconnect to existing session ID
FR-7Terminate sessionP1Clean shutdown
FR-8Get session statusP1Files changed, tokens used, etc.
FR-9Export session historyP2For logging/audit
FR-10Handle permission requestsP2Forward to user, relay response
FR-11Multi-instance supportP2Connect to multiple ACP servers
FR-12Auto-reconnectP2Handle network interruptions

Non-Functional Requirements

IDRequirementTargetNotes
NFR-1Response time< 2sTime from user message to ACP call
NFR-2Streaming latency< 500msAgent output → user notification
NFR-3Concurrent sessions10+Per OpenClaw instance
NFR-4Session persistence24h+Survive restarts
NFR-5Error recoveryAuto-retryExponential backoff on connection loss

Technical Constraints

  1. No OpenCode Modifications: Use ACP as-is, don’t fork OpenCode
  2. Protocol Compliance: Speak standard ACP (if it becomes multi-tool protocol)
  3. OpenClaw Native: Tool must feel native to OpenClaw (same patterns as browser, message, etc.)
  4. Stateless Gateway: OpenClaw Gateway restarts shouldn’t lose session IDs (persist config/state)

Success Metrics

MVP (Phase 1)

  • Can create session and send message from WhatsApp
  • Can list active sessions
  • Can get session status
  • Works with local opencode acp instance

Production-Ready (Phase 2)

  • Supports remote ACP servers
  • Auto-reconnect on network issues
  • Permission approval flow working
  • 5+ concurrent sessions stable

Advanced (Phase 3)

  • Multi-instance management
  • Session export/import
  • Team collaboration features (shared sessions)

Open Questions

  1. ACP Protocol Maturity: Is ACP stable? Documented? Versioned?
  2. Authentication: Does ACP require auth tokens? How does OpenClaw authenticate?
  3. WebSocket vs HTTP: Which protocol for what? (HTTP for commands, WS for streaming?)
  4. Session Persistence: Does opencode acp persist sessions to disk? Across restarts?
  5. Multi-User: Can multiple clients connect to same session? (e.g., mob programming)
  6. opencode web vs acp: Does opencode web expose ACP endpoints? Or separate process needed?

Next Steps

  1. Protocol Discovery: Run opencode acp and document endpoints (curl/wscat exploration)
  2. Proof of Concept: Build minimal Node.js script that creates session + sends message
  3. Design Tool Interface: Define OpenClaw tool functions and parameters
  4. Implement MVP: Session create, message send, status check
  5. Test in Production: Deploy to real OpenClaw instance, use via WhatsApp

References

  • OpenCode GitHub: https://github.com/sweetpad-dev/opencode
  • OpenCode Docs: (check for ACP documentation) <<<<<<< HEAD
  • Existing Bridge Plugin: /workspace/projects/ai-dev/plugins/opencode-bridge/
  • coding-agent Skill: /app/skills/coding-agent/SKILL.md =======
  • Existing Bridge Plugin: projects/ai-dev/plugins/opencode-bridge/ (if it exists)
  • coding-agent Skill: app/skills/coding-agent/SKILL.md (relative to OpenClaw root)

f146a548fbab991798ce91719b88cbf1f064588a

Graph View