跳转到内容
展示 生态 源码解读 文档

Server

opencode serve 命令运行一个无头的 HTTP server，它暴露了一个 OpenAPI 端点，opencode 客户端可以使用该端点。

Usage

opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]

Options

FlagDescriptionDefault
--port监听的端口4096
--hostname监听的主机名127.0.0.1
--mdns启用 mDNS 发现false
--mdns-domainmDNS 服务的自定义域名opencode.local
--cors允许的额外浏览器来源[]

--cors 可以重复传入：

opencode serve --cors http://localhost:5173 --cors https://app.example.com

Authentication

设置 OPENCODE_SERVER_PASSWORD，使用 HTTP basic auth 来保护 server。用户名默认为 opencode，也可以通过设置 OPENCODE_SERVER_USERNAME 来覆盖。这同时适用于 opencode serve 和 opencode web。

OPENCODE_SERVER_PASSWORD=your-password opencode serve

How it works

当你运行 opencode 时，它会启动一个 TUI 和一个 server。其中 TUI 是与 server 通信的 client。Server 暴露了一个 OpenAPI 3.1 规范端点。该端点同时也用于生成 SDK。

这种架构让 opencode 能够支持多个 client，并允许你以编程方式与 opencode 交互。

你可以运行 opencode serve 来启动一个独立的 server。如果你已经运行了 opencode TUI，那么 opencode serve 会启动一个新的 server。

Connect to an existing server

当你启动 TUI 时，它会随机分配一个端口和主机名。你也可以传入 --hostname 和 --port 参数，然后使用这些值连接到它的 server。

/tui 端点可用于通过 server 驱动 TUI。例如，你可以预填或运行一个 prompt。这种设置被 OpenCode IDE 插件所使用。

Spec

Server 发布了一个 OpenAPI 3.1 规范，可以在此查看：

http://<hostname>:<port>/doc

例如：http://localhost:4096/doc。使用该规范来生成 client 或检查请求与响应类型，也可以在 Swagger 浏览器中查看。

APIs

opencode server 暴露了以下 API。

Global

MethodPathDescriptionResponse
GET/global/health获取 server 的健康状态和版本{ healthy: true, version: string }
GET/global/event获取全局事件（SSE 流）事件流

Project

MethodPathDescriptionResponse
GET/project列出所有项目Project[]
GET/project/current获取当前项目Project

Path & VCS

MethodPathDescriptionResponse
GET/path获取当前路径Path
GET/vcs获取当前项目的 VCS 信息VcsInfo

Instance

MethodPathDescriptionResponse
POST/instance/dispose释放当前实例boolean

Config

MethodPathDescriptionResponse
GET/config获取配置信息Config
PATCH/config更新配置Config
GET/config/providers列出 providers 和默认模型{ providers: Provider[], default: { [key: string]: string } }

Provider

MethodPathDescriptionResponse
GET/provider列出所有 providers{ all: Provider[], default: {...}, connected: string[] }
GET/provider/auth获取 provider 的认证方式{ [providerID: string]: ProviderAuthMethod[] }
POST/provider/{id}/oauth/authorize使用 OAuth 授权一个 providerProviderAuthAuthorization
POST/provider/{id}/oauth/callback处理 provider 的 OAuth 回调boolean

Sessions

MethodPathDescriptionNotes
GET/session列出所有 sessions返回 Session[]
POST/session创建一个新的 sessionbody: { parentID?, title? }，返回 Session
GET/session/status获取所有 sessions 的状态返回 { [sessionID: string]: SessionStatus }
GET/session/:id获取 session 详情返回 Session
DELETE/session/:id删除一个 session 及其所有数据返回 boolean
PATCH/session/:id更新 session 属性body: { title? }，返回 Session
GET/session/:id/children获取一个 session 的子 sessions返回 Session[]
GET/session/:id/todo获取 session 的 todo 列表返回 Todo[]
POST/session/:id/init分析应用并创建 AGENTS.mdbody: { messageID, providerID, modelID }，返回 boolean
POST/session/:id/fork在某条消息处 fork 一个现有 sessionbody: { messageID? }，返回 Session
POST/session/:id/abort中止一个正在运行的 session返回 boolean
POST/session/:id/share分享一个 session返回 Session
DELETE/session/:id/share取消分享一个 session返回 Session
GET/session/:id/diff获取该 session 的 diffquery: messageID?，返回 FileDiff[]
POST/session/:id/summarize摘要 sessionbody: { providerID, modelID }，返回 boolean
POST/session/:id/revert回滚一条 messagebody: { messageID, partID? }，返回 boolean
POST/session/:id/unrevert恢复所有已回滚的 messages返回 boolean
POST/session/:id/permissions/:permissionID响应一个权限请求body: { response, remember? }，返回 boolean

Messages

MethodPathDescriptionNotes
GET/session/:id/message列出会话中的 messagesquery: limit?，返回 { info: Message, parts: Part[] }[]
POST/session/:id/message发送一条消息并等待响应body: { messageID?, model?, agent?, noReply?, system?, tools?, parts }，返回 { info: Message, parts: Part[] }
GET/session/:id/message/:messageID获取 message 详情返回 { info: Message, parts: Part[] }
POST/session/:id/prompt_async异步发送消息（不等待）body：与 /session/:id/message 相同，返回 204 No Content
POST/session/:id/command执行一条斜杠命令body: { messageID?, agent?, model?, command, arguments }，返回 { info: Message, parts: Part[] }
POST/session/:id/shell运行 shell 命令body: { agent, model?, command }，返回 { info: Message, parts: Part[] }

Commands

MethodPathDescriptionResponse
GET/command列出所有 commandsCommand[]

Files

MethodPathDescriptionResponse
GET/find?pattern=<pat>在文件中搜索文本包含 path、lines、line_number、absolute_offset、submatches 的匹配对象数组
GET/find/file?query=<q>按名称查找文件和目录string[]（路径列表）
GET/find/symbol?query=<q>查找工作区中的符号Symbol[]
GET/file?path=<path>列出文件和目录FileNode[]
GET/file/content?path=<p>读取文件FileContent
GET/file/status获取跟踪文件的状态File[]

/find/file query parameters

  • query（必填）— 搜索字符串（模糊匹配）
  • type（可选）— 将结果限制为 "file" 或 "directory"
  • directory（可选）— 覆盖搜索的项目根目录
  • limit（可选）— 最大结果数（1–200）
  • dirs（可选）— 旧版标志（"false" 表示仅返回文件）

Tools (Experimental)

MethodPathDescriptionResponse
GET/experimental/tool/ids列出所有 tool IDsToolIDs
GET/experimental/tool?provider=<p>&model=<m>列出指定模型下的工具及其 JSON schemasToolList

LSP, Formatters & MCP

MethodPathDescriptionResponse
GET/lsp获取 LSP server 状态LSPStatus[]
GET/formatter获取 formatter 状态FormatterStatus[]
GET/mcp获取 MCP server 状态{ [name: string]: MCPStatus }
POST/mcp动态添加 MCP serverbody: { name, config }，返回 MCP 状态对象

Agents

MethodPathDescriptionResponse
GET/agent列出所有可用的 agentsAgent[]

Logging

MethodPathDescriptionResponse
POST/log写入日志条目。Body: { service, level, message, extra? }boolean

TUI

MethodPathDescriptionResponse
POST/tui/append-prompt追加文本到 promptboolean
POST/tui/open-help打开帮助对话框boolean
POST/tui/open-sessions打开 session 选择器boolean
POST/tui/open-themes打开主题选择器boolean
POST/tui/open-models打开模型选择器boolean
POST/tui/submit-prompt提交当前 promptboolean
POST/tui/clear-prompt清除 promptboolean
POST/tui/execute-command执行一条命令（{ command }）boolean
POST/tui/show-toast显示 toast（{ title?, message, variant }）boolean
GET/tui/control/next等待下一个 control 请求control 请求对象
POST/tui/control/response响应一个 control 请求（{ body }）boolean

Auth

MethodPathDescriptionResponse
PUT/auth/:id设置认证凭据。Body 必须匹配 provider schemaboolean

Events

MethodPathDescriptionResponse
GET/eventServer-sent events 流。第一个事件是 server.connected，之后是 bus 事件Server-sent events 流

Docs

MethodPathDescriptionResponse
GET/docOpenAPI 3.1 规范包含 OpenAPI 规范的 HTML 页