OpenCode CLI Integration

This skill is designed for AI agents like OpenClaw to execute coding tasks via OpenCode CLI.

OpenCode is an AI-powered code editor CLI. When called via OpenClaw, only CLI mode is used.

Security Scope

What this skill does:

• Integrates with OpenCode CLI for coding tasks
• Manages sessions, plans, and builds
• Optionally connects to configured MCP servers (Playwright, Supabase, Context7)

What this skill does NOT do:

• Install or modify system-wide packages
• Access credentials outside configured MCP servers
• Persist beyond user-initiated sessions

Credential access:

• MCP servers (if configured) may use environment variables like SUPABASE_URL, SUPABASE_ANON_KEY, CONTEXT7_API_KEY
• Skills run in project context; avoid committing secrets to version control
• Only use this skill in repositories/environments you trust

Core Command

opencode run -m <provider/model> -- "<prompt>"

Example:

opencode run -m <provider/model> -- "Add error handling to the login function"

Plan→Build Workflow (Core)

⚠️ Key Rule: Maintain Same Session

Correct approach:

# 1. Start Plan (creates session)
opencode run -m <model> -- 'Analyze task, output plan.'

# 2. Wait for user APPROVE

# 3. Switch to Build (continue same session)
opencode run --continue --agent build -- 'Implement approved plan.'

Wrong approach (context lost):

❌ opencode run --agent plan "..."   # session A
❌ opencode run --agent build "..."  # session B (separate!)

Agent Options

Session Management

opencode run --continue -- '<prompt>'
opencode run --session <id> -- '<prompt>'
opencode run --continue --fork -- '<prompt>'
opencode session list
opencode session delete <id>

OpenClaw Integration

Standard Task

opencode run -m <model> -- '<task>'

Background Task

opencode run -m <model> -- '<task>'
process action:poll sessionId:<id> timeout:30000
process action:log sessionId:<id>
process action:kill sessionId:<id>

Monitoring Discipline

⚠️ Mandatory: After starting, must actively monitor. Do not wait for system event.

Start → Get sessionId
  ↓
Every 30-60s: poll + log
  ↓
Progress → Report
Error → Report immediately
Complete → Report result (do not wait for event)

Violation criteria:

• Start without monitoring → Abandoning responsibility
• User asks "is it done?" before checking → Failure

MCP Integration

OpenCode supports MCP integration to extend capabilities. Must run in project root directory.

Common tools: Playwright (UI automation), Supabase (database)

Scenario guide:

Built-in Tools

OpenCode Agent built-in tools: read/write/edit, bash, grep/glob, todowrite, skill, webfetch

Scenario guide:

Practical Tips

• File reference: Use @filename to quickly reference files
• Undo changes: /undo to undo, /redo to restore

Scenario guide:

Skills Configuration

Scenario guide:

Common Patterns

Note: Examples use openclaw system event for optional task notification. This is an OpenClaw platform command. Omit if running outside OpenClaw.

Planning Task

opencode run -m <model> -- 'Analyze task, output plan.'

For detailed plan format, see project workflow documentation.

Implementation Task

opencode run -m <model> -- 'Execute approved plan.'

Verify with: npm run build && npm test

Database Operations

cd /path/to/project
opencode run -m <model> -- 'Use Supabase MCP for database operations.'

See: references/mcp-config-guide.md for MCP setup.

UI Testing

opencode run -m <model> -- 'Use Playwright MCP for UI testing.'

See: references/mcp-config-guide.md for MCP setup.

Troubleshooting

sysctl not found

export PATH="/usr/sbin:/usr/bin:/sbin:/bin:$PATH"

MCP not loading

Ensure running in project root:

cd /path/to/project && opencode run ...

See: references/mcp-config-guide.md

Session context lost

Use --continue instead of separate starts:

✅ opencode run --continue --agent build "..."
❌ opencode run --agent build "..."

Quick Reference

Common Commands

OpenClaw Integration

Configuration Guide Index

CLI Integration v2.6 - 2026-04-05