OpenCode Server API Skill Handbook#

Version: v4.6.0 | Server: v1.2.15 | oho CLI: v1.1.2

⚠️ Important: All OpenCode operations must be sent via oho CLI. Python SDK or curl are no longer supported.

---

🚫 Telegram Message Guidelines (Important)#

Prohibited Content:

• ❌ Do not send notifications like "There are updates", "Skill has been updated"
• ❌ Do not send formatted version changelogs
• ❌ Do not send lengthy confirmation reports after task submission

Correct Approach:

• ✅ Return only a concise session ID and status after task submission
• ✅ Notify users only when there is substantial progress
• ✅ Keep messages brief and direct

Example:

text

✅ Task submitted
Session: ses_xxx
Project: babylon3DWorld

---

🚀 Quick Start#

Submit Tasks (Async Mode to Avoid Timeout)#

bash

# Most common: create session + send message in one command, `directory` is the project path
oho add "Fix login bug" --title "Bug Fix" --directory /mnt/d/fe/babylon3DWorld --model "minimax-cn-coding-plan:MiniMax-M2.7" --no-reply

# Another example: summarize today's progress
oho add "Summarize today's changes" --title "Command Test" --directory /mnt/d/fe/opencode_cli --model "minimax-cn-coding-plan:MiniMax-M2.7" --no-reply

# Specify Agent
oho add "@hephaestus Fix login bug" --title "Bug Fix" --directory /mnt/d/fe/project --model "minimax-cn-coding-plan:MiniMax-M2.7" --no-reply

# Attach files
oho add "Analyze logs" --file /var/log/app.log --directory /mnt/d/fe/project --no-reply

Key Parameters#

ParameterTypeDescriptionDefault--titlestringSession title (auto-generated if not provided)Auto-generated--parentstringParent session ID (for creating child sessions)---directorystringSession working directory, project pathCurrent directory--agentstringAgent ID for the message---modelstringModel ID for the message (e.g., provider:model)minimax-cn-coding-plan/MiniMax-M2.7--no-replyboolDo not wait for AI responsefalse--systemstringSystem prompt---toolsstring[]Tool list (can be specified multiple times)---filestring[]File attachments (can be specified multiple times)---timeoutintRequest timeout in seconds300-j, --jsonboolJSON outputfalse

---

📋 Common Commands#

Session Management#

bash

# List all sessions
oho session list

# Filter by ID (fuzzy match)
oho session list --id ses_abc

# Filter by title (fuzzy)
oho session list --title "test"

# Filter by project ID
oho session list --project-id proj1

# Filter by directory
oho session list --directory babylon

# Filter by timestamp
oho session list --created 1773537883643
oho session list --updated 1773538142930

# Filter by status
oho session list --status running    # running/completed/error/aborted/idle
oho session list --running           # Show only running sessions

# Sort and pagination
oho session list --sort updated --order desc  # Sort by updated descending
oho session list --limit 10 --offset 0        # Pagination

# JSON output
oho session list -j

# Create session
oho session create
oho session create --title "name"
oho session create --parent ses_xxx    # Create child session
oho session create --path /path        # Create in specified directory

# Get session details
oho session get <id>

# Update session
oho session update <id> --title "New Title"

# Get child sessions
oho session children <id>

# Get todo items
oho session todo <id>

# Branch session
oho session fork <id>

# Abort session
oho session abort <id>

# Share/unshare session
oho session share <id>
oho session unshare <id>

# Get file diff
oho session diff <id>

# Session summary
oho session summarize <id>

# Revert message
oho session revert <id> --message <msg-id>
oho session unrevert <id>

# Respond to permission request
oho session permissions <id> <perm-id> --response allow

# Delete session
oho session delete ses_xxx

# Archive session
oho session achieve <id> --directory /mnt/d/fe/project

Message Management#

bash

# List messages
oho message list -s ses_xxx

# Get message details
oho message get -s ses_xxx <msg-id>

# Send message (sync)
oho message add -s ses_xxx "Continue task"

# Send async (don't wait for response)
oho message prompt-async -s ses_xxx "Task content"

# Execute command
oho message command -s ses_xxx /help

# Run shell command
oho message shell -s ses_xxx --agent default "ls -la"

Project Management#

bash

# List all projects
oho project list

# Get current project
oho project current

# Get current path
oho path

# Get VCS info
oho vcs

# Dispose current instance
oho instance dispose

Global Commands#

bash

# Check server health
oho global health

# Listen to global event stream (SSE)
oho global event

Configuration Management#

bash

# Get configuration
oho config get

# Update configuration
oho config set --theme dark

# List providers
oho config providers

Provider Management#

bash

# List all providers
oho provider list

# Get authentication methods
oho provider auth

# OAuth authorization
oho provider oauth authorize <id>

# Handle callback
oho provider oauth callback <id>

File Operations#

bash

# List files
oho file list [path]

# Read file content
oho file content <path>

# Get file status
oho file status

Find Commands#

bash

# Search text
oho find text "pattern"

# Find files
oho find file "query"

# Find symbols
oho find symbol "query"

Other Commands#

bash

# List agents
oho agent list

# List commands
oho command list

# List tool IDs
oho tool ids

# List tools
oho tool list --provider xxx --model xxx

# LSP status
oho lsp status

# Formatter status
oho formatter status

# MCP servers
oho mcp list
oho mcp add <name> --config '{}'

# TUI
oho tui open-help
oho tui show-toast --message "message"

# Auth setup
oho auth set <provider> --credentials key=value

---

⚠️ Timeout Handling (Important)#

The oho add command waits for AI response by default. For complex tasks, the AI may need more time to think, which could cause timeout.

Ways to Avoid Timeout#

Method 1: Use --no-reply Parameter (Recommended)

bash

# ✅ Returns immediately after sending message, no waiting for AI response
oho add "Analyze project structure" --directory /mnt/d/fe/project --no-reply

# Check results later
oho message list -s <session-id>

Method 2: Increase Timeout

bash

# Set timeout to 10 minutes (600 seconds)
export OPENCODE_CLIENT_TIMEOUT=600
oho add "Complex task" --directory /mnt/d/fe/project

# Or set temporarily
OPENCODE_CLIENT_TIMEOUT=600 oho add "Complex task" --directory /mnt/d/fe/project

Method 3: Use --timeout Parameter (Most Convenient)

bash

# Temporarily set timeout to 10 minutes
oho add "Complex task" --directory /mnt/d/fe/project --timeout 600

# Set timeout to 1 hour
oho add "Large refactor" --directory /mnt/d/fe/project --timeout 3600

Method 4: Use Async Commands

bash

# Create session first
oho session create --title "task" --path /mnt/d/fe/project

# Send message async
oho message prompt-async -s <session-id> "Task description"

Timeout Configuration#

Configuration MethodPriorityDescription--timeout parameterHighestTemporary override, only effective for current commandOPENCODE_CLIENT_TIMEOUT env varMediumEffective for current shell sessionDefault valueLowest300 seconds (5 minutes)

Timeout Error Messages#

If timeout occurs, you will see a friendly error:

text

Request timeout (300 seconds)

Suggestions:
  1. Use --no-reply parameter to avoid waiting
  2. Increase timeout via env var: export OPENCODE_CLIENT_TIMEOUT=600
  3. Use async command: oho message prompt-async -s <session-id> "task"

Background Polling (Optional)#

bash

#!/bin/bash
session_id=$(oho add "task" --directory /mnt/d/fe/project --json | jq -r '.sessionId')

while true; do
    count=$(oho message list -s "$session_id" -j | jq 'length')
    [ "$count" -ge 2 ] && echo "✅ Done" && break
    echo "⏳ Running... ($count messages)"
    sleep 10
done

---

🤖 Agent System#

AgentRoleUse Cases**@sisyphusMain coordinatorLarge feature development, parallel execution@hephaestusDeep workerCode exploration, performance optimization@prometheus**Strategic plannerRequirements clarification, architecture design

---

📝 Practical Examples#

babylon3DWorld Project Tasks#

bash

#!/bin/bash
# Submit coding task

oho add "@hephaestus ulw optimize navigation logic between editor and world pages

**Coding Goals**:
1. When returning from editor to world page: refresh directly, no longer check if editor made changes
2. When entering editor from world page: no longer cache the world itself

**Keywords**: ulw" \
  --directory /mnt/d/fe/babylon3DWorld \
  --title "ulw - Optimize editor navigation logic" \
  --no-reply

echo "✅ Task submitted"

Multi-Project Batch Tasks#

bash

#!/bin/bash
# Batch submit tasks

oho add "Task 1" --directory /mnt/d/fe/babylon3DWorld --no-reply
oho add "Task 2" --directory /mnt/d/fe/wujimanager --no-reply
oho add "Task 3" --directory /mnt/d/fe/armdraw --no-reply

echo "✅ All tasks submitted"

---

OpenCode Server Usage#

1. rerun.sh

text

#!/bin/bash

echo "🔴 stopping opencode web service..."
pkill -f "opencode web"
sleep 2

if pgrep -f "opencode web" > /dev/null; then
    pkill -9 -f "opencode web"
    sleep 1
fi

echo "✅ opencode web stopped"
echo "🟢 starting opencode web service..."
bash run.sh &

echo "✅ opencode web started"

1. run.sh

text

OPENCODE_SERVER_PASSWORD=cs516123456 opencode web --hostname 0.0.0.0  --port 4096 --mdns --mdns-domain opencode.local

🔧 Troubleshooting#

Restart OpenCode Server#

Standard Restart (Recommended):

bash

# Switch to project directory and run restart script
cd /mnt/d/fe && bash rerun.sh &

Description:

• rerun.sh automatically stops old service and starts new one
• Use & to run in background to avoid blocking
• Wait 3-5 seconds after restart for service to fully start

Verify Service is Running:

bash

# Wait for service to start
sleep 5

# Check processes
ps aux | grep "opencode web"

# Test API
oho session list

View Logs:

bash

# View run.sh output logs
tail -f /tmp/opencode.log

# Or view recent logs
tail -50 /tmp/opencode.log

If Restart Script Gets Stuck:

bash

# Force kill stuck process
pkill -9 -f "bash rerun.sh"

# Manual restart
cd /mnt/d/fe
pkill -f "opencode web"
sleep 2
OPENCODE_SERVER_PASSWORD=yourpassword opencode web --hostname 0.0.0.0 --port 4096 --mdns --mdns-domain opencode.local &

401 Unauthorized#

bash

# Check password
echo $OPENCODE_SERVER_PASSWORD

# Or specify via command line
oho --password yourpassword session list

Session Not Found#

bash

# Recreate session
oho session create --path /mnt/d/fe/babylon3DWorld

Task Timeout#

bash

# Use --no-reply to submit async
oho add "task" --directory /mnt/d/fe/project --no-reply

ConfigInvalidError (500 Error)#

Symptoms:

bash

Error: API Error [500]: {"name":"ConfigInvalidError","data":{"path":"/path/to/project/.opencode/opencode.json","issues":[...]}}

Cause: The opencode.json or .opencode/opencode.json config file in the project does not comply with the schema requirements.

Common Errors:

json

// ❌ Wrong: tools.lint should be boolean, not object
{
  "tools": {
    "lint": {
      "type": "shell",
      "command": ["yarn", "lint"]
    }
  }
}

// ❌ Wrong: lsp config format is incorrect
{
  "lsp": {
    "vue": {
      "disabled": false  // Should be true/false, but schema expects different format
    }
  }
}

Solution:

bash

# 1. Backup incorrect config file
mv opencode.json opencode.json.bak
mv .opencode/opencode.json .opencode/opencode.json.bak

# 2. Restart opencode server (using rerun.sh)
cd /mnt/d/fe && bash rerun.sh &

# 3. Verify service is running
sleep 5
oho session list

# 4. If you need config, use correct format
cat > .opencode/opencode.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "model": "alibaba-cn/qwen3.5-plus"
}
EOF

Prevention:

• Backup opencode.json before modifying
• Use oho config get to verify config is valid
• Reference official schema: https://opencode.ai/config.json

---

🔗 MCP Server#

oho can act as an MCP (Model Context Protocol) server, allowing external MCP clients (like Claude Desktop, Cursor, etc.) to call OpenCode API via MCP protocol.

Start MCP Server#

bash

# Start MCP server (stdio mode)
oho mcpserver

Available MCP Tools#

ToolDescriptionsession_listList all sessionssession_createCreate new sessionsession_getGet session detailssession_deleteDelete sessionsession_statusGet all session statusesmessage_listList messages in sessionmessage_addSend message to sessionconfig_getGet OpenCode configurationproject_listList all projectsproject_currentGet current projectprovider_listList AI providersfile_listList files in directoryfile_contentRead file contentfind_textSearch text in projectfind_fileFind files by nameglobal_healthCheck server health status

MCP Client Configuration#

Claude Desktop (macOS/Windows)

Add to claude_desktop_config.json:

json

{
  "mcpServers": {
    "oho": {
      "command": "oho",
      "args": ["mcpserver"],
      "env": {
        "OPENCODE_SERVER_HOST": "127.0.0.1",
        "OPENCODE_SERVER_PORT": "4096",
        "OPENCODE_SERVER_PASSWORD": "your-password"
      }
    }
  }
}

Cursor

Add to Cursor settings (JSON mode):

json

{
  "mcpServers": {
    "oho": {
      "command": "oho",
      "args": ["mcpserver"],
      "env": {
        "OPENCODE_SERVER_HOST": "127.0.0.1",
        "OPENCODE_SERVER_PORT": "4096",
        "OPENCODE_SERVER_PASSWORD": "your-password"
      }
    }
  }
}

---

🔗 Related Resources#

• OpenCode Official Docs: https://opencode.ai/docs/
• oho CLI Repository: https://github.com/tornado404/opencode_cli
• OpenAPI Spec: http://localhost:4096/doc

---

Created: 2026-02-27 13:46 CST

Last Updated: 2026-04-02 00:43 CST - Added session achieve command