opencode API接口文档：二次开发与系统集成必备参考

1. OpenCode 是什么：一个真正为开发者设计的终端AI编程助手

OpenCode 不是又一个网页版 AI 编程玩具，也不是需要登录、上传代码、依赖云端算力的“伪本地”工具。它是一个用 Go 编写的、开箱即用的终端原生 AI 编程框架，2024 年开源后迅速在开发者社区引发关注——GitHub 星标突破 5 万，月活跃用户达 65 万，MIT 协议完全开放商用。

它的核心定位很清晰：终端优先、多模型支持、隐私安全、零代码存储。你可以把它理解成“你的本地 AI 编程副驾驶”，不是替代你写代码，而是让你在敲命令、读日志、改配置、查文档时，随时调出一个懂上下文、能理解项目结构、会主动建议重构路径的智能伙伴。

它不强制你用某个模型，也不要求你注册账号。你可以用 Claude 做逻辑推理，用 GPT 做文案润色，用 Gemini 查最新 API 文档，也可以把本地跑着的 Qwen3-4B-Instruct-2507 模型直接接入——所有切换都在终端里按 Tab 键完成，无需重启、无需配置文件重写。

更重要的是，它默认不上传任何一行代码、不保存任何对话历史、不记录你的项目路径。整个执行环境通过 Docker 隔离，模型推理、插件运行、代码分析全部发生在你自己的机器上。对重视数据主权的团队、处理敏感业务的工程师、或是只想安静写代码不想被“训练”的个人开发者来说，这不只是功能，而是底线。

2. 为什么需要 API 文档：从“用起来”到“接进去”

很多开发者第一次运行 opencode 后，会被 TUI 界面的流畅感和 Agent 的响应速度打动。但很快就会遇到真实问题：

• 想把 OpenCode 的“代码重构建议”嵌入到公司内部的 CI 流水线里，自动扫描 PR 中的坏味道；
• 想在 VS Code 插件中调用 OpenCode 的“函数级补全”能力，而不是依赖 LSP 的通用补全；
• 想让运维同学用企业微信机器人触发 OpenCode 分析一段报错日志，并返回可执行的修复步骤；
• 想把本地运行的 Qwen3-4B-Instruct-2507 模型，同时供给 OpenCode 和另一个自研工具使用，避免重复加载。

这些场景，靠 opencode 命令行交互已经不够了。你需要的是稳定、明确、可编程的接口契约——也就是本文要讲的 OpenCode API。

它不是隐藏的调试接口，也不是临时拼凑的内部调用。OpenCode 从架构设计之初就将 API 作为一等公民：服务端（opencode-server）提供标准 HTTP 接口，客户端（opencode-cli）全部基于这套 API 构建，所有插件、IDE 集成、远程控制都走同一套通道。这意味着，你今天写的集成脚本，明天升级 OpenCode 版本后依然可用。

3. API 核心能力概览：不是“能调用”，而是“能做什么”

OpenCode API 不是简单地把聊天接口暴露出来。它围绕“编程任务”这一核心，抽象出 5 类语义明确的能力模块，每类都对应真实开发动作：

3.1 会话管理（Sessions）

• 创建/列出/删除会话，支持命名、标签、超时设置
• 每个会话独立维护上下文、模型绑定、插件启用状态
• 支持并发会话：一个用于代码审查，一个用于文档生成，互不干扰

3.2 代码理解与生成（Code Intelligence）

• POST /v1/code/analyze：传入文件路径或代码片段，返回结构化分析结果（函数列表、依赖关系、潜在风险点）
• POST /v1/code/generate：基于当前项目上下文生成新函数、测试用例、README 片段
• POST /v1/code/refactor：传入代码块 + 重构目标（如“提取为独立函数”、“转换为 async/await”），返回修改建议与 diff

3.3 模型调度与推理（Model Orchestration）

• GET /v1/models：获取当前可用模型列表（含名称、提供商、是否本地、基准得分）
• POST /v1/inference：绕过会话，直接向指定模型发送 prompt，返回原始响应（适合批处理）
• 支持流式响应（text/event-stream），适配长输出场景（如生成完整单元测试）

3.4 插件控制（Plugin Control）

• GET /v1/plugins：列出已安装插件及其状态（启用/禁用）、权限声明（如“可读取剪贴板”）
• POST /v1/plugins/{id}/invoke：以 JSON 参数调用插件方法（如 google-search 插件接收查询词并返回摘要）
• 插件间可通过 plugin:// 协议互相调用，形成轻量工作流

3.5 系统状态与诊断（System Health）

• GET /v1/health：返回内存占用、模型加载状态、插件健康度、最近错误日志摘要
• GET /v1/metrics：暴露 Prometheus 格式指标（请求延迟、成功率、token 使用量）
• POST /v1/debug/dump：生成当前会话完整上下文快照（用于复现问题）

关键区别提醒：OpenCode API 不提供“通用聊天”接口。它没有 /v1/chat/completions 这样的泛化 endpoint。所有接口都绑定具体编程意图——你要么在分析代码，要么在生成代码，要么在调用插件。这种设计让集成方无需做语义解析，直接映射业务动作到 API 调用，大幅降低误用率和维护成本。

4. 快速上手：三步启动 API 服务并调用第一个接口

OpenCode API 默认不随 CLI 启动，需显式启用服务端。整个过程无需编译、不依赖 Node.js 或 Python，纯 Go 二进制搞定。

4.1 启动服务端（含 vLLM 后端对接）

假设你已在本地运行 vLLM 服务（监听 http://localhost:8000/v1），且已按文档配置好 opencode.json：

# 1. 启动 OpenCode 服务端（监听 3000 端口）
opencode-server --port 3000 --config ./opencode.json

# 2. 验证服务是否就绪（返回 200 OK）
curl -s http://localhost:3000/health | jq .status
# 输出： "ok"

# 3. 查看当前模型列表（应包含 Qwen3-4B-Instruct-2507）
curl -s http://localhost:3000/v1/models | jq '.models[] | select(.name == "Qwen3-4B-Instruct-2507")'

4.2 调用代码分析接口：真实场景演示

我们用一个极简但高频的场景：分析一段有 bug 的 Go 代码，让 OpenCode 返回可操作的修复建议。

待分析代码（save as buggy.go）：

func calculateTotal(items []int) int {
    total := 0
    for i := 0; i <= len(items); i++ { // ← bug：越界访问
        total += items[i]
    }
    return total
}

调用 API 获取分析结果：

curl -X POST http://localhost:3000/v1/code/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "language": "go",
    "code": "func calculateTotal(items []int) int {\\n    total := 0\\n    for i := 0; i <= len(items); i++ {\\n        total += items[i]\\n    }\\n    return total\\n}",
    "context": {
      "filename": "buggy.go",
      "project_root": "/path/to/your/project"
    }
  }' | jq '.analysis.suggestions[0]'

预期返回（精简）：

{
  "title": "数组索引越界风险",
  "description": "循环条件 i <= len(items) 会导致 i 在最后一次迭代时等于 len(items)，而 items[i] 访问的是第 len(items)+1 个元素，超出切片范围。",
  "fix": "将循环条件改为 i < len(items)",
  "line": 3,
  "column": 18
}

这个例子展示了 API 的核心价值：输入是开发者最自然的表达（代码文本+上下文），输出是可直接落地的工程建议（带位置、带修复方案），而非模糊的“请检查边界”。

5. 二次开发实战：用 Python 脚本自动修复 Git 提交中的常见错误

API 的真正威力，在于它能无缝融入你的现有工具链。下面是一个真实可用的 Python 脚本示例，它会在 git commit 前自动扫描新增/修改的 .go 文件，调用 OpenCode API 分析潜在问题，并将修复建议写入暂存区，供你确认。

#!/usr/bin/env python3
# save as pre-commit-hook.py
import subprocess
import json
import requests
import sys

OPENCODE_API = "http://localhost:3000/v1"

def get_staged_go_files():
    """获取暂存区中所有 .go 文件"""
    result = subprocess.run(
        ["git", "diff", "--cached", "--name-only", "--diff-filter=ACM", "*.go"],
        capture_output=True, text=True
    )
    return [f.strip() for f in result.stdout.splitlines() if f.strip()]

def analyze_file(filepath):
    """调用 OpenCode API 分析单个文件"""
    try:
        with open(filepath, "r", encoding="utf-8") as f:
            code = f.read()
        
        response = requests.post(
            f"{OPENCODE_API}/code/analyze",
            json={
                "language": "go",
                "code": code,
                "context": {"filename": filepath}
            },
            timeout=30
        )
        response.raise_for_status()
        return response.json()
    except Exception as e:
        print(f"[WARN] 分析 {filepath} 失败: {e}")
        return None

def apply_fix(filepath, suggestion):
    """根据建议内容，用 sed 替换文件内容（简化版，实际需更健壮）"""
    try:
        # 此处仅为示意：替换整行（生产环境需精确到列）
        with open(filepath, "r") as f:
            lines = f.readlines()
        
        line_idx = suggestion["line"] - 1
        if 0 <= line_idx < len(lines):
            old_line = lines[line_idx]
            new_line = old_line.replace("i <= len(items)", "i < len(items)")
            lines[line_idx] = new_line
            
            with open(filepath, "w") as f:
                f.writelines(lines)
            
            # 重新添加到暂存区
            subprocess.run(["git", "add", filepath])
            print(f"[INFO] 已自动修复 {filepath} 第 {suggestion['line']} 行")
    except Exception as e:
        print(f"[ERROR] 自动修复失败: {e}")

if __name__ == "__main__":
    go_files = get_staged_go_files()
    if not go_files:
        sys.exit(0)
    
    print(f"[INFO] 检测到 {len(go_files)} 个待提交的 Go 文件...")
    for file in go_files:
        analysis = analyze_file(file)
        if analysis and analysis.get("analysis", {}).get("suggestions"):
            for sug in analysis["analysis"]["suggestions"][:1]:  # 只处理第一个建议
                apply_fix(file, sug)

使用方式：

# 将脚本放入 .git/hooks/pre-commit（需 chmod +x）
# 下次 git commit 时，它会自动运行

这个脚本没有魔法，但它把 OpenCode 的能力转化成了实实在在的工程效率：把 AI 的洞察力，变成 Git 工作流中的一环。你不需要改变开发习惯，AI 就在背后默默帮你兜底。

6. 集成注意事项与避坑指南

API 很强大，但直接上手容易踩坑。以下是来自真实集成项目的 4 条硬核经验：

6.1 模型加载时机：别在首次请求时才等模型热身

OpenCode Server 启动时默认不预加载模型，首次调用 /v1/inference 才触发加载。这对 CLI 用户无感，但对自动化脚本可能是灾难性的——一次 curl 请求可能卡住 20 秒。

正确做法：启动服务后，立即发一个轻量探测请求：

# 启动服务后立即执行
curl -X POST http://localhost:3000/v1/inference \
  -H "Content-Type: application/json" \
  -d '{"model": "Qwen3-4B-Instruct-2507", "messages": [{"role":"user","content":"hi"}]}' \
  --max-time 5 2>/dev/null || true

这会触发模型加载，后续请求即可获得稳定低延迟。

6.2 上下文长度管理：API 不会自动截断，你得负责

OpenCode API 不会对传入的 code 字段做长度限制或智能截断。如果你传入一个 5000 行的文件，而模型上下文只有 4K token，API 会原样转发给 vLLM，最终返回 context_length_exceeded 错误。

推荐策略：

• 对 > 500 行的文件，先用 POST /v1/code/analyze 获取关键函数/类的位置；
• 再用 GET /v1/code/extract?file=path&start=100&end=150（需自行实现或调用插件）提取相关片段；
• 最后将精炼后的上下文送入生成接口。

6.3 插件权限：不是所有插件都默认可用

部分插件（如 clipboard-read、shell-exec）涉及系统权限，默认处于禁用状态。API 调用时若返回 plugin_disabled，需先调用 PATCH /v1/plugins/{id} 启用。

安全建议：在 CI/CD 等非交互环境中，只启用明确需要的插件，并在服务启动时通过 --plugins-enabled 参数预设：

opencode-server --plugins-enabled "git-status,github-pr" ...

6.4 错误码语义：比 HTTP 状态码更重要的是 body 中的 error.code

OpenCode API 统一返回 400 Bad Request，但真正的错误类型藏在响应体中：

error.code	含义	应对
model_not_found	指定模型未注册	检查 opencode.json 配置，调用 /v1/models 确认
context_too_large	代码+上下文超过模型容量	主动分块或精简输入
plugin_not_installed	插件未安装	运行 opencode plugin install <id>
session_expired	会话超时（默认 30 分钟）	调用 /v1/sessions/create 新建

记住：永远先检查 response.json().get("error", {}).get("code")，而不是只看 HTTP 状态码。

7. 总结：API 是 OpenCode 赋能组织的真正入口

OpenCode 的魅力，始于终端里那个流畅的 TUI 界面，但它的价值上限，由 API 定义。

• 如果你是个体开发者，API 让你能把 AI 能力注入到自己最顺手的编辑器、脚本、自动化流程中，不再被界面束缚；
• 如果你是团队技术负责人，API 提供了标准化的集成契约，让 AI 编程能力可以像数据库连接池一样，被多个内部系统复用、监控、治理；
• 如果你是平台工程师，API 的清晰分层（会话、代码、模型、插件）让你能基于它构建更上层的 IDE 插件市场、企业知识库问答、甚至低代码 AI 工作流引擎。

它不鼓吹“取代程序员”，而是坚定地站在“增强程序员”的立场——用最小的学习成本，提供最大的工程杠杆。当你不再需要记住一堆模型参数、不再纠结 prompt 工程、不再手动复制粘贴分析结果，而是用几行 curl 或一个 Python 函数，就把 AI 的洞察力变成一行 git add、一次 CI 修复、一个 Slack 通知时，你就真正用对了 OpenCode。

而这一切的起点，就是这份文档所描述的、稳定、明确、面向工程的 API。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。