微信扫一扫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
| Agent | Purpose |
|-------|---------|
| plan | Planning, analysis, design |
| build | Implementation, coding, modification |
| explore | Codebase exploration |
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:
| Scenario | Reference |
|----------|-----------|
| Need UI automation testing (Playwright) | references/mcp-config-guide.md |
| Need database operations (Supabase) | references/mcp-config-guide.md |
| MCP not loading, troubleshoot config | references/mcp-config-guide.md |
Built-in Tools
OpenCode Agent built-in tools: read/write/edit, bash, grep/glob, todowrite, skill, webfetch
Scenario guide:
| Scenario | Reference |
|----------|-----------|
| Unsure if Agent can perform an operation | references/built-in-tools-guide.md |
| Plan Agent reports insufficient permissions | references/built-in-tools-guide.md (see tool permissions table) |
Practical Tips
- File reference: Use
@filenameto quickly reference files - Undo changes:
/undoto undo,/redoto restore
Scenario guide:
| Scenario | Reference |
|----------|-----------|
| Want to reference file instead of typing path | references/tips-guide.md (file reference) |
| Made mistake and want to rollback | references/tips-guide.md (undo/redo) |
| Want to learn TUI shortcuts | references/tips-guide.md (shortcuts) |
Skills Configuration
Scenario guide:
| Scenario | Reference |
|----------|-----------|
| Want to add custom skill | references/skills-config-guide.md |
| Unsure where to place skill files | references/skills-config-guide.md |
Common Patterns
Note: Examples use
openclaw system eventfor 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
| Task | Command |
|------|---------|
| Plan task | opencode run -m <model> -- 'Analyze...' |
| Build (continue session) | opencode run --continue --agent build -- 'Implement...' |
| Continue last session | opencode run --continue |
| Specific session | opencode run --session <id> |
| Fork session | opencode run --continue --fork |
| List sessions | opencode session list |
| Delete session | opencode session delete <id> |
| View models | opencode models |
OpenClaw Integration
| Task | Command |
|------|---------|
| Background task | pty:true background:true command:"opencode run..." |
| Monitor progress | process action:poll sessionId:<id> |
| View logs | process action:log sessionId:<id> |
| Terminate task | process action:kill sessionId:<id> |
Configuration Guide Index
| Scenario | Reference |
|----------|-----------|
| UI automation / Database operations | references/mcp-config-guide.md |
| Agent tool capabilities / Permissions | references/built-in-tools-guide.md |
| Shortcuts / File reference / Undo | references/tips-guide.md |
| Add custom skill | references/skills-config-guide.md |
CLI Integration v2.6 - 2026-04-05