OpenCode Server：HTTP API 接口完整参考
OpenCode 内置了一个 HTTP 服务器，运行 opencode serve 即可启动。服务器提供完整的 OpenAPI 3.1 接口，支持会话管理、消息发送、文件操作、LSP/格式化状态查询和 TUI 控制。可设置 Basic Auth 保护接口安全。
opencode serve 命令启动一个无头 HTTP 服务器，暴露 OpenAPI 接口供客户端使用。这与 OpenCode TUI 的工作方式相同——TUI 本质上就是这个服务器的一个客户端。
启动服务器
opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]| 参数 | 说明 | 默认值 |
|---|---|---|
--port |
监听端口 | 4096 |
--hostname |
监听主机名 | 127.0.0.1 |
--mdns |
启用 mDNS 发现 | false |
--mdns-domain |
mDNS 自定义域名 | opencode.local |
--cors |
允许的额外浏览器 origin | [] |
--cors 可以多次指定：
opencode serve --cors http://localhost:5173 --cors https://app.example.com认证
设置 OPENCODE_SERVER_PASSWORD 启用 HTTP Basic Auth（用户名默认为 opencode，可通过 OPENCODE_SERVER_USERNAME 修改）：
OPENCODE_SERVER_PASSWORD=your-password opencode serveOpenAPI 规范
服务器在以下地址提供 OpenAPI 3.1 规范：
http://<hostname>:<port>/doc可用于生成客户端代码或在 Swagger 界面中浏览 API。
连接到运行中的 TUI
TUI 启动时会随机分配端口。你可以通过固定端口让工具连接到 TUI：
opencode --port 4096然后通过 /tui 系列接口控制 TUI（如预填 Prompt、执行命令），这正是 IDE 插件的工作方式。
API 参考
全局
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/global/health |
服务器健康状态和版本 |
GET |
/global/event |
全局事件流（SSE） |
项目
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/project |
列出所有项目 |
GET |
/project/current |
获取当前项目 |
路径与 VCS
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/path |
获取当前路径 |
GET |
/vcs |
获取 VCS 信息 |
配置
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/config |
获取配置信息 |
PATCH |
/config |
更新配置 |
GET |
/config/providers |
列出 Provider 和默认模型 |
Provider
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/provider |
列出所有 Provider |
GET |
/provider/auth |
获取 Provider 认证方式 |
POST |
/provider/{id}/oauth/authorize |
OAuth 认证 |
POST |
/provider/{id}/oauth/callback |
OAuth 回调处理 |
会话
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/session |
列出所有会话 |
POST |
/session |
创建新会话 |
GET |
/session/status |
所有会话状态 |
GET |
/session/:id |
获取会话详情 |
DELETE |
/session/:id |
删除会话 |
PATCH |
/session/:id |
更新会话属性 |
GET |
/session/:id/children |
获取子会话 |
GET |
/session/:id/todo |
获取会话待办列表 |
POST |
/session/:id/init |
分析应用并创建 AGENTS.md |
POST |
/session/:id/fork |
Fork 会话 |
POST |
/session/:id/abort |
中止运行中的会话 |
POST |
/session/:id/share |
分享会话 |
DELETE |
/session/:id/share |
取消分享 |
GET |
/session/:id/diff |
获取会话的 diff |
POST |
/session/:id/summarize |
摘要会话 |
POST |
/session/:id/revert |
回滚消息 |
POST |
/session/:id/unrevert |
恢复回滚的消息 |
POST |
/session/:id/permissions/:permissionID |
响应权限请求 |
消息
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/session/:id/message |
列出会话消息 |
POST |
/session/:id/message |
发送消息并等待响应 |
GET |
/session/:id/message/:messageID |
获取消息详情 |
POST |
/session/:id/prompt_async |
异步发送消息（不等待响应，204 响应） |
POST |
/session/:id/command |
执行 Slash 命令 |
POST |
/session/:id/shell |
运行 Shell 命令 |
文件
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/find?pattern=<pat> |
搜索文件内容 |
GET |
/find/file?query=<q> |
按名称查找文件/目录 |
GET |
/find/symbol?query=<q> |
查找工作区符号 |
GET |
/file?path=<path> |
列出文件和目录 |
GET |
/file/content?path=<p> |
读取文件内容 |
GET |
/file/status |
获取跟踪文件状态 |
/find/file 查询参数：query（必须）、type（file/directory）、directory、limit（1-200）
LSP / Formatters / MCP
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/lsp |
LSP 服务器状态 |
GET |
/formatter |
格式化器状态 |
GET |
/mcp |
MCP 服务器状态 |
POST |
/mcp |
动态添加 MCP 服务器 |
Agents
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/agent |
列出所有可用 Agent |
TUI 控制
| 方法 | 路径 | 说明 |
|---|---|---|
POST |
/tui/append-prompt |
向提示框追加文本 |
POST |
/tui/open-help |
打开帮助对话框 |
POST |
/tui/open-sessions |
打开会话选择器 |
POST |
/tui/open-themes |
打开主题选择器 |
POST |
/tui/open-models |
打开模型选择器 |
POST |
/tui/submit-prompt |
提交当前 Prompt |
POST |
/tui/clear-prompt |
清空 Prompt |
POST |
/tui/execute-command |
执行命令 |
POST |
/tui/show-toast |
显示 Toast 通知 |
GET |
/tui/control/next |
等待下一个控制请求 |
POST |
/tui/control/response |
响应控制请求 |
认证 / 事件 / 工具
| 方法 | 路径 | 说明 |
|---|---|---|
PUT |
/auth/:id |
设置认证凭证 |
GET |
/event |
SSE 事件流（首个事件为 server.connected） |
POST |
/log |
写入日志 |
GET |
/experimental/tool/ids |
列出所有工具 ID |
GET |
/experimental/tool |
列出工具及 JSON Schema |
GET |
/doc |
OpenAPI 3.1 规范（HTML） |
常见问题
Q: opencode serve 和直接运行 opencode 有什么区别？
A: 直接运行 opencode 同时启动 TUI 和服务器，TUI 作为服务器的客户端。opencode serve 只启动服务器，没有 TUI，适合远程访问或程序化使用场景。
Q: 如何从外网访问 OpenCode 服务器？
A: 使用 --hostname 0.0.0.0 监听所有网络接口，并设置 OPENCODE_SERVER_PASSWORD 启用认证。注意做好网络安全配置。
Q: SSE 事件流包含哪些事件？
A: 订阅 /event 后首先收到 server.connected 事件，之后会接收所有内部总线事件，包括会话状态变化、消息更新、工具执行等。具体事件类型参见插件文档。