>_OpenCode
~/content/server

Server

Interact with opencode server over HTTP.

last_updated: "2026-01-20"

opencode serve 命令运行一个无头的 HTTP 服务器，该服务器公开一个 OpenAPI 端点，opencode 客户端可以使用该端点。

用法

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

选项

FlagDescriptionDefault
--port监听端口4096
--hostname监听主机名127.0.0.1
--mdns启用 mDNS 发现false
--cors允许的其他浏览器来源[]

--cors 可以多次传递：

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

身份验证

设置 OPENCODE_SERVER_PASSWORD 以使用 HTTP 基本身份验证保护服务器。 用户名默认为 opencode，或设置 OPENCODE_SERVER_USERNAME 以覆盖它。 这适用于 opencode serve 和 opencode web。

bash
OPENCODE_SERVER_PASSWORD=your-password opencode serve

工作原理

当你运行 opencode 时，它会启动一个 TUI 和一个服务器。 其中 TUI 是与服务器通信的客户端。 服务器公开一个 OpenAPI 3.1 规范端点。 此端点也用于生成 SDK。

Note

💡 Tip

使用 opencode 服务器以编程方式与 opencode 交互。

此架构使 opencode 支持多个客户端，并允许你以编程方式与 opencode 交互。

你可以运行 opencode serve 来启动一个独立的服务器。 如果你正在运行 opencode TUI，opencode serve 将启动一个新的服务器。

连接到现有服务器

当你启动 TUI 时，它会随机分配一个端口和主机名。 你可以改为传入 --hostname 和 --port flags。 然后使用它连接到其服务器。

/tui 端点可用于通过服务器驱动 TUI。 例如，你可以预填充或运行提示。 OpenCode IDE 插件使用此设置。

Spec

服务器发布一个 OpenAPI 3.1 规范，可以在以下位置查看：

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

例如，http://localhost:4096/doc。 使用该规范生成客户端或检查请求和响应类型。 或者在 Swagger 浏览器中查看它。

APIs

opencode 服务器公开以下 API。

Global

MethodPathDescriptionResponse
GET/global/health获取服务器运行状况和版本{ healthy: true, version: string }
GET/global/event获取全局事件 (SSE 流)Event stream

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列出所有会话返回 Session[]
POST/session创建新会话body: { parentID?, title? }, 返回 Session
GET/session/status获取所有会话的会话状态返回 { [sessionID: string]: SessionStatus }
GET/session/:id获取会话详细信息返回 Session
DELETE/session/:id删除会话及其所有数据返回 boolean
PATCH/session/:id更新会话属性body: { title? }, 返回 Session
GET/session/:id/children获取会话的子会话返回 Session[]
GET/session/:id/todo获取会话的待办事项列表返回 Todo[]
POST/session/:id/init分析应用程序并创建 AGENTS.mdbody: { messageID, providerID, modelID }, 返回 boolean
POST/session/:id/fork在消息处 Fork 现有会话body: { messageID? }, 返回 Session
POST/session/:id/abort中止正在运行的会话返回 boolean
POST/session/:id/share共享会话返回 Session
DELETE/session/:id/share取消共享会话返回 Session
GET/session/:id/diff获取此会话的差异query: messageID?, 返回 FileDiff[]
POST/session/:id/summarize总结会话body: { providerID, modelID }, 返回 boolean
POST/session/:id/revert还原消息body: { messageID, partID? }, 返回 boolean
POST/session/:id/unrevert恢复所有已还原的消息返回 boolean
POST/session/:id/permissions/:permissionID响应权限请求body: { response, remember? }, 返回 boolean

Messages

MethodPathDescriptionNotes
GET/session/:id/message列出对话中的消息query: 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获取消息详情返回 { 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列出所有命令Command[]

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 (必填) — 搜索字符串（模糊匹配）
  • type (可选) — 将结果限制为 "file" 或 "directory"
  • directory (可选) — 覆盖搜索的项目根目录
  • limit (可选) — 最大结果数 (1–200)
  • dirs (可选) — 遗留标志 ("false" 仅返回文件)

Tools (Experimental)

MethodPathDescriptionResponse
GET/experimental/tool/ids列出所有工具 IDToolIDs
GET/experimental/tool?provider=<p>&model=<m>列出具有模型 JSON schemas 的工具ToolList

LSP, Formatters & MCP

MethodPathDescriptionResponse
GET/lsp获取 LSP 服务器状态LSPStatus[]
GET/formatter获取格式化程序状态FormatterStatus[]
GET/mcp获取 MCP 服务器状态{ [name: string]: MCPStatus }
POST/mcp动态添加 MCP 服务器body: { name, config }, 返回 MCP 状态对象

Agents

MethodPathDescriptionResponse
GET/agent列出所有可用代理Agent[]

Logging

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

TUI

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

Auth

MethodPathDescriptionResponse
PUT/auth/:id设置身份验证凭据。Body 必须匹配提供程序模式boolean

Events

MethodPathDescriptionResponse
GET/event服务器发送事件流。第一个事件是 server.connected，然后是总线事件服务器发送事件流

Docs

MethodPathDescriptionResponse
GET/docOpenAPI 3.1 规范包含 OpenAPI 规范的 HTML 页面
Comments (Coming Soon)

Configure Giscus in environment variables to enable comments.