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:

✅ Task submitted
Session: ses_xxx
Project: babylon3DWorld

🚀 Quick Start

Submit Tasks (Async Mode to Avoid Timeout)

CODEBLOCK1

Key Parameters

📋 Common Commands

Session Management

CODEBLOCK2

Message Management

CODEBLOCK3

Project Management

CODEBLOCK4

Global Commands

CODEBLOCK5

Configuration Management

CODEBLOCK6

Provider Management

CODEBLOCK7

File Operations

CODEBLOCK8

Find Commands

CODEBLOCK9

Other Commands

CODEBLOCK10

⚠️ 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)
CODEBLOCK11

Method 2: Increase Timeout
CODEBLOCK12

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

Method 4: Use Async Commands
CODEBLOCK14

Timeout Configuration

Timeout Error Messages

If timeout occurs, you will see a friendly error:
CODEBLOCK15

Background Polling (Optional)

CODEBLOCK16

🤖 Agent System

📝 Practical Examples

babylon3DWorld Project Tasks

CODEBLOCK17

Multi-Project Batch Tasks

CODEBLOCK18

OpenCode Server Usage

1. 1. rerun.sh

CODEBLOCK19

1. 2. run.sh

CODEBLOCK20

🔧 Troubleshooting

Restart OpenCode Server

Standard Restart (Recommended):
CODEBLOCK21

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:
CODEBLOCK22

View Logs:
CODEBLOCK23

If Restart Script Gets Stuck:
CODEBLOCK24

401 Unauthorized

Session Not Found

Task Timeout

ConfigInvalidError (500 Error)

Symptoms:
CODEBLOCK28

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

Common Errors:
CODEBLOCK29

Solution:
CODEBLOCK30

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

CODEBLOCK31

Available MCP Tools

MCP Client Configuration

Claude Desktop (macOS/Windows)

Add to claude_desktop_config.json:

CODEBLOCK32

Cursor

Add to Cursor settings (JSON mode):

CODEBLOCK33

🔗 Related Resources

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