OpenCode Server

OpenCode Server 是整个系统的核心大脑，负责与 LLM 通信、管理上下文、执行工具调用以及权限控制。运行 opencode serve 命令会启动一个无头 HTTP 服务器，该服务器公开 OpenAPI 端点，OpenCode 客户端可通过该端点与之交互。

使用方法 (Usage)

终端执行命令：

opencode serve [--port <数字>] [--hostname <字符串>] [--cors <源>]

选项 (Options)

标志	描述	默认值
`--port`	监听端口	`4096`
`--hostname`	监听主机名	`127.0.0.1`
`--mdns`	启用 mDNS 发现	`false`
`--cors`	允许的额外浏览器源	`[]`

--cors 可多次传递：

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

身份验证 (Authentication)

设置 OPENCODE_SERVER_PASSWORD 以通过 HTTP 基本身份验证保护服务器。用户名默认为 opencode，也可通过 OPENCODE_SERVER_USERNAME 覆盖。该设置适用于 opencode serve 和 opencode web。

OPENCODE_SERVER_PASSWORD=你的密码 opencode serve

工作原理 (How it works)

运行 opencode 时，会启动 TUI（终端用户界面）和服务器，其中 TUI 作为客户端与服务器通信。服务器公开 OpenAPI 3.1 规范端点，该端点也用于生成 SDK。

可通过 opencode serve 启动独立服务器；若已运行 OpenCode TUI，opencode serve 会启动新服务器。
启动 TUI 时，它会随机分配端口和主机名，也可通过 --hostname 和 --port 标志指定，进而连接到对应的服务器。
/tui 端点可通过服务器控制 TUI，例如预填充或运行提示，OpenCode IDE 插件即采用此设置。

规范 (OpenAPI Specification)

服务器发布的 OpenAPI 3.1 规范可通过以下地址查看：

http://<主机名>:<端口>/doc

例如 http://localhost:4096/doc，可利用该规范生成客户端或检查请求和响应类型，也可在 Swagger 探索器中查看。

API 列表 (API Reference)

1. Global (全局)

方法	路径	描述	响应
`GET`	`/global/health`	获取服务器健康状态和版本	`{ healthy: true, version: string }`
`GET`	`/global/event`	获取全局事件（SSE 流）	事件流

2. Project (项目)

方法	路径	描述	响应
`GET`	`/project`	列出所有项目	`Project[]`
`GET`	`/project/current`	获取当前项目	`Project`

3. Path & VCS (路径与版本控制)

方法	路径	描述	响应
`GET`	`/path`	获取当前路径	`Path`
`GET`	`/vcs`	获取当前项目的版本控制系统信息	`VcsInfo`

4. Instance (实例管理)

方法	路径	描述	响应
`POST`	`/instance/dispose`	销毁当前实例	`boolean`

5. Config (配置)

方法	路径	描述	响应
`GET`	`/config`	获取配置信息	`Config`
`PATCH`	`/config`	更新配置	`Config`
`GET`	`/config/providers`	列出提供商和默认模型	`{ providers: Provider[], default: { [key: string]: string } }`

6. Provider (服务商)

方法	路径	描述	响应
`GET`	`/provider`	列出所有提供商	`{ all: Provider[], default: {...}, connected: string[] }`
`GET`	`/provider/auth`	获取提供商身份验证方法	`{ [providerID: string]: ProviderAuthMethod[] }`
`POST`	`/provider/{id}/oauth/authorize`	通过 OAuth 授权提供商	`ProviderAuthAuthorization`
`POST`	`/provider/{id}/oauth/callback`	处理提供商的 OAuth 回调	`boolean`

7. Sessions (会话管理)

方法	路径	描述	说明
`GET`	`/session`	列出所有会话	返回 `Session[]`
`POST`	`/session`	创建新会话	请求体：`{ parentID?, title? }`，返回 `Session`
`GET`	`/session/status`	获取所有会话的状态	返回 `{ [sessionID: string]: SessionStatus }`
`GET`	`/session/:id`	获取会话详情	返回 `Session`
`DELETE`	`/session/:id`	删除会话及其所有数据	返回 `boolean`
`PATCH`	`/session/:id`	更新会话属性	请求体：`{ title? }`，返回 `Session`
`GET`	`/session/:id/children`	获取会话的子会话	返回 `Session[]`
`GET`	`/session/:id/todo`	获取会话的待办列表	返回 `Todo[]`
`POST`	`/session/:id/init`	分析应用并创建 `AGENTS.md`	请求体：`{ messageID, providerID, modelID }`，返回 `boolean`
`POST`	`/session/:id/fork`	在某条消息处复制现有会话	请求体：`{ messageID? }`，返回 `Session`
`POST`	`/session/:id/abort`	中止运行中的会话	返回 `boolean`
`POST`	`/session/:id/share`	共享会话	返回 `Session`
`DELETE`	`/session/:id/share`	取消共享会话	返回 `Session`
`GET`	`/session/:id/diff`	获取该会话的差异	查询参数：`messageID?`，返回 `FileDiff[]`
`POST`	`/session/:id/summarize`	总结会话	请求体：`{ providerID, modelID }`，返回 `boolean`
`POST`	`/session/:id/revert`	撤销消息	请求体：`{ messageID, partID? }`，返回 `boolean`
`POST`	`/session/:id/unrevert`	恢复所有已撤销消息	返回 `boolean`
`POST`	`/session/:id/permissions/:permissionID`	响应权限请求	请求体：`{ response, remember? }`，返回 `boolean`

8. Messages (消息管理)

方法	路径	描述	说明
`GET`	`/session/:id/message`	列出会话中的消息	查询参数：`limit?`，返回 `{ info: Message, parts: Part[] }[]`
`POST`	`/session/:id/message`	发送消息并等待响应	请求体：`{ 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`	异步发送消息（不等待）	请求体与 `/session/:id/message` 相同，返回 `204 No Content`
`POST`	`/session/:id/command`	执行斜杠命令	请求体：`{ messageID?, agent?, model?, command, arguments }`，返回 `{ info: Message, parts: Part[] }`
`POST`	`/session/:id/shell`	运行 shell 命令	请求体：`{ agent, model?, command }`，返回 `{ info: Message, parts: Part[] }`

9. Commands (命令)

方法	路径	描述	响应
`GET`	`/command`	列出所有命令	`Command[]`

10. Files (文件操作)

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

/find/file 查询参数：

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

11. Tools (工具 - 实验性)

方法	路径	描述	响应
`GET`	`/experimental/tool/ids`	列出所有工具 ID	`ToolIDs`
`GET`	`/experimental/tool?provider=<提供商>&model=<模型>`	列出带 JSON 模式的模型工具	`ToolList`

12. LSP, Formatters & MCP (语言服务与扩展)

方法	路径	描述	响应
`GET`	`/lsp`	获取 LSP 服务器状态	`LSPStatus[]`
`GET`	`/formatter`	获取格式化程序状态	`FormatterStatus[]`
`GET`	`/mcp`	获取 MCP 服务器状态	`{ [name: string]: MCPStatus }`
`POST`	`/mcp`	动态添加 MCP 服务器	请求体：`{ name, config }`，返回 MCP 状态对象

13. Agents (智能体)

方法	路径	描述	响应
`GET`	`/agent`	列出所有可用代理	`Agent[]`

14. Logging (日志)

方法	路径	描述	响应
`POST`	`/log`	写入日志条目	请求体：`{ service, level, message, extra? }`，返回 `boolean`

15. TUI (界面控制)

方法	路径	描述	响应
`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`	显示提示	请求体：`{ title?, message, variant }`，返回 `boolean`
`GET`	`/tui/control/next`	等待下一个控制请求	控制请求对象
`POST`	`/tui/control/response`	响应控制请求	请求体：`{ body }`，返回 `boolean`

16. Auth (身份验证)

方法	路径	描述	响应
`PUT`	`/auth/:id`	设置身份验证凭据	请求体必须匹配提供商架构，返回 `boolean`

17. Events (事件流)

方法	路径	描述	响应
`GET`	`/event`	服务器发送事件流	第一个事件为 `server.connected`，之后为总线事件

18. Docs (文档)

方法	路径	描述	响应
`GET`	`/doc`	OpenAPI 3.1 规范	带 OpenAPI 规范的 HTML 页面

Intro (入门)

Usage (使用指南)

Configure (详细配置)

Develop (开发)