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#

bash

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

Example:

bash

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

---

Plan→Build Workflow (Core)#

⚠️ Key Rule: Maintain Same Session#

Correct approach:

bash

# 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):

bash

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

Agent Options#

AgentPurposeplanPlanning, analysis, designbuildImplementation, coding, modificationexploreCodebase exploration

---

Session Management#

bash

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#

bash

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

Background Task#

bash

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.

text

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:

ScenarioReferenceNeed UI automation testing (Playwright)references/mcp-config-guide.mdNeed database operations (Supabase)references/mcp-config-guide.mdMCP not loading, troubleshoot configreferences/mcp-config-guide.md

---

Built-in Tools#

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

Scenario guide:

ScenarioReferenceUnsure if Agent can perform an operationreferences/built-in-tools-guide.mdPlan Agent reports insufficient permissionsreferences/built-in-tools-guide.md (see tool permissions table)

---

Practical Tips#

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

Scenario guide:

ScenarioReferenceWant to reference file instead of typing pathreferences/tips-guide.md (file reference)Made mistake and want to rollbackreferences/tips-guide.md (undo/redo)Want to learn TUI shortcutsreferences/tips-guide.md (shortcuts)

---

Skills Configuration#

Scenario guide:

ScenarioReferenceWant to add custom skillreferences/skills-config-guide.mdUnsure where to place skill filesreferences/skills-config-guide.md

---

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#

bash

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

For detailed plan format, see project workflow documentation.

Implementation Task#

bash

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

Verify with: npm run build && npm test

Database Operations#

bash

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#

bash

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

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

---

Troubleshooting#

sysctl not found#

bash

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

MCP not loading#

Ensure running in project root:

bash

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

See: references/mcp-config-guide.md

Session context lost#

Use --continue instead of separate starts:

bash

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

---

Quick Reference#

Common Commands#

TaskCommandPlan taskopencode run -m <model> -- 'Analyze...'Build (continue session)opencode run --continue --agent build -- 'Implement...'Continue last sessionopencode run --continueSpecific sessionopencode run --session <id>Fork sessionopencode run --continue --forkList sessionsopencode session listDelete sessionopencode session delete <id>View modelsopencode models

OpenClaw Integration#

TaskCommandBackground taskpty:true background:true command:"opencode run..."Monitor progressprocess action:poll sessionId:<id>View logsprocess action:log sessionId:<id>Terminate taskprocess action:kill sessionId:<id>

Configuration Guide Index#

ScenarioReferenceUI automation / Database operationsreferences/mcp-config-guide.mdAgent tool capabilities / Permissionsreferences/built-in-tools-guide.mdShortcuts / File reference / Undoreferences/tips-guide.mdAdd custom skillreferences/skills-config-guide.md

---

CLI Integration v2.6 - 2026-04-05