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 serve

---

OpenAPI 规范

服务器在以下地址提供 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 事件，之后会接收所有内部总线事件，包括会话状态变化、消息更新、工具执行等。具体事件类型参见插件文档。