服务器
通过 HTTP 与 opencode 服务器交互。
opencode serve 命令运行一个无头 HTTP 服务器，它暴露一个 opencode 客户端可以使用的 OpenAPI 端点。
使用
opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]选项
| 标志 | 说明 | 默认值 |
|---|---|---|
--port | 监听的端口 | 4096 |
--hostname | 监听的主机名 | 127.0.0.1 |
--mdns | 启用 mDNS 发现 | false |
--mdns-domain | mDNS 服务的自定义域名 | opencode.local |
--cors | 额外允许的浏览器源 | [] |
--cors 可以多次传入：
opencode serve --cors http://localhost:5173 --cors https://app.example.com认证
设置 OPENCODE_SERVER_PASSWORD 以用 HTTP basic auth 保护服务器。用户名默认为 opencode，或设置 OPENCODE_SERVER_USERNAME 来覆盖它。这对 opencode serve 和 opencode web 都适用。
OPENCODE_SERVER_PASSWORD=your-password opencode serve工作原理
当你运行 opencode 时，它会启动一个 TUI 和一个服务器。其中 TUI 是与服务器通信的客户端。服务器暴露一个 OpenAPI 3.1 规范端点。该端点也用于生成 SDK。
提示： 使用 opencode 服务器以编程方式与 opencode 交互。
这种架构让 opencode 能够支持多个客户端，并允许你以编程方式与 opencode 交互。
你可以运行 opencode serve 来启动一个独立的服务器。如果你有 opencode TUI 正在运行，opencode serve 会启动一个新服务器。
连接到现有服务器
当你启动 TUI 时，它会随机分配一个端口和主机名。你可以改为传入 --hostname 和 --port 标志，然后用它来连接到其服务器。
/tui 端点可用于通过服务器驱动 TUI。例如，你可以预填或运行一个提示词。OpenCode IDE 插件就使用了这种设置。
规范
服务器发布一个 OpenAPI 3.1 规范，可在以下地址查看：
http://<hostname>:<port>/doc例如 http://localhost:4096/doc。使用该规范来生成客户端或检查请求和响应类型，或在 Swagger 浏览器中查看它。
API
opencode 服务器暴露以下 API。
Global
| 方法 | 路径 | 说明 | 响应 |
|---|---|---|---|
GET | /global/health | 获取服务器健康状态和版本 | { healthy: true, version: string } |
GET | /global/event | 获取全局事件（SSE 流） | 事件流 |
Project
| 方法 | 路径 | 说明 | 响应 |
|---|---|---|---|
GET | /project | 列出所有项目 | Project[] (opens in a new tab) |
GET | /project/current | 获取当前项目 | Project (opens in a new tab) |
Path & VCS
| 方法 | 路径 | 说明 | 响应 |
|---|---|---|---|
GET | /path | 获取当前路径 | Path (opens in a new tab) |
GET | /vcs | 获取当前项目的 VCS 信息 | VcsInfo (opens in a new tab) |
Instance
| 方法 | 路径 | 说明 | 响应 |
|---|---|---|---|
POST | /instance/dispose | 释放当前实例 | boolean |
Config
| 方法 | 路径 | 说明 | 响应 |
|---|---|---|---|
GET | /config | 获取配置信息 | Config (opens in a new tab) |
PATCH | /config | 更新配置 | Config (opens in a new tab) |
GET | /config/providers | 列出提供商和默认模型 | { providers: Provider[] (opens in a new tab), default: { [key: string]: string } } |
Provider
| 方法 | 路径 | 说明 | 响应 |
|---|---|---|---|
GET | /provider | 列出所有提供商 | { all: Provider[] (opens in a new tab), default: {...}, connected: string[] } |
GET | /provider/auth | 获取提供商认证方法 | { [providerID: string]: ProviderAuthMethod[] (opens in a new tab) } |
POST | /provider/{id}/oauth/authorize | 使用 OAuth 授权一个提供商 | ProviderAuthAuthorization (opens in a new tab) |
POST | /provider/{id}/oauth/callback | 处理某个提供商的 OAuth 回调 | boolean |
Sessions
| 方法 | 路径 | 说明 | 备注 |
|---|---|---|---|
GET | /session | 列出所有会话 | 返回 Session[] (opens in a new tab) |
POST | /session | 创建一个新会话 | body: { parentID?, title? }，返回 Session (opens in a new tab) |
GET | /session/status | 获取所有会话的会话状态 | 返回 { [sessionID: string]: SessionStatus (opens in a new tab) } |
GET | /session/:id | 获取会话详情 | 返回 Session (opens in a new tab) |
DELETE | /session/:id | 删除一个会话及其所有数据 | 返回 boolean |
PATCH | /session/:id | 更新会话属性 | body: { title? }，返回 Session (opens in a new tab) |
GET | /session/:id/children | 获取一个会话的子会话 | 返回 Session[] (opens in a new tab) |
GET | /session/:id/todo | 获取一个会话的待办列表 | 返回 Todo[] (opens in a new tab) |
POST | /session/:id/init | 分析应用并创建 AGENTS.md | body: { messageID, providerID, modelID }，返回 boolean |
POST | /session/:id/fork | 在某条消息处 fork 一个现有会话 | body: { messageID? }，返回 Session (opens in a new tab) |
POST | /session/:id/abort | 中止一个正在运行的会话 | 返回 boolean |
POST | /session/:id/share | 分享一个会话 | 返回 Session (opens in a new tab) |
DELETE | /session/:id/share | 取消分享一个会话 | 返回 Session (opens in a new tab) |
GET | /session/:id/diff | 获取此会话的 diff | query: messageID?，返回 FileDiff[] (opens in a new tab) |
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
| 方法 | 路径 | 说明 | 备注 |
|---|---|---|---|
GET | /session/:id/message | 列出一个会话中的消息 | query: limit?，返回 { info: Message (opens in a new tab), parts: Part[] (opens in a new tab)}[] |
POST | /session/:id/message | 发送一条消息并等待响应 | body: { messageID?, model?, agent?, noReply?, system?, tools?, parts }，返回 { info: Message (opens in a new tab), parts: Part[] (opens in a new tab)} |
GET | /session/:id/message/:messageID | 获取消息详情 | 返回 { info: Message (opens in a new tab), parts: Part[] (opens in a new tab)} |
POST | /session/:id/prompt_async | 异步发送一条消息（不等待） | body: 与 /session/:id/message 相同，返回 204 No Content |
POST | /session/:id/command | 执行一个斜杠命令 | body: { messageID?, agent?, model?, command, arguments }，返回 { info: Message (opens in a new tab), parts: Part[] (opens in a new tab)} |
POST | /session/:id/shell | 运行一个 shell 命令 | body: { agent, model?, command }，返回 { info: Message (opens in a new tab), parts: Part[] (opens in a new tab)} |
Commands
| 方法 | 路径 | 说明 | 响应 |
|---|---|---|---|
GET | /command | 列出所有命令 | Command[] (opens in a new tab) |
Files
| 方法 | 路径 | 说明 | 响应 |
|---|---|---|---|
GET | /find?pattern=<pat> | 在文件中搜索文本 | 包含 path、lines、line_number、absolute_offset、submatches 的匹配对象数组 |
GET | /find/file?query=<q> | 按名称查找文件和目录 | string[]（路径） |
GET | /find/symbol?query=<q> | 查找工作区符号 | Symbol[] (opens in a new tab) |
GET | /file?path=<path> | 列出文件和目录 | FileNode[] (opens in a new tab) |
GET | /file/content?path=<p> | 读取一个文件 | FileContent (opens in a new tab) |
GET | /file/status | 获取被跟踪文件的状态 | File[] (opens in a new tab) |
/find/file 查询参数
query（必需）—— 搜索字符串（模糊匹配）type（可选）—— 将结果限制为"file"或"directory"directory（可选）—— 为本次搜索覆盖项目根目录limit（可选）—— 最大结果数（1-200）dirs（可选）—— 遗留标志（"false"仅返回文件）
Tools（实验性）
| 方法 | 路径 | 说明 | 响应 |
|---|---|---|---|
GET | /experimental/tool/ids | 列出所有工具 ID | ToolIDs (opens in a new tab) |
GET | /experimental/tool?provider=<p>&model=<m> | 列出某个模型带 JSON schema 的工具 | ToolList (opens in a new tab) |
LSP、Formatters 与 MCP
| 方法 | 路径 | 说明 | 响应 |
|---|---|---|---|
GET | /lsp | 获取 LSP 服务器状态 | LSPStatus[] (opens in a new tab) |
GET | /formatter | 获取格式化器状态 | FormatterStatus[] (opens in a new tab) |
GET | /mcp | 获取 MCP 服务器状态 | { [name: string]: MCPStatus (opens in a new tab) } |
POST | /mcp | 动态添加 MCP 服务器 | body: { name, config }，返回 MCP 状态对象 |
Agents
| 方法 | 路径 | 说明 | 响应 |
|---|---|---|---|
GET | /agent | 列出所有可用的 agents | Agent[] (opens in a new tab) |
Logging
| 方法 | 路径 | 说明 | 响应 |
|---|---|---|---|
POST | /log | 写入日志条目。Body: { service, level, message, extra? } | boolean |
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 | 显示 toast（{ title?, message, variant }） | boolean |
GET | /tui/control/next | 等待下一个控制请求 | 控制请求对象 |
POST | /tui/control/response | 响应一个控制请求（{ body }） | boolean |
Auth
| 方法 | 路径 | 说明 | 响应 |
|---|---|---|---|
PUT | /auth/:id | 设置认证凭据。Body 必须匹配提供商 schema | boolean |
Events
| 方法 | 路径 | 说明 | 响应 |
|---|---|---|---|
GET | /event | 服务器发送事件（SSE）流。第一个事件是 server.connected，然后是总线事件 | 服务器发送事件流 |
Docs
| 方法 | 路径 | 说明 | 响应 |
|---|---|---|---|
GET | /doc | OpenAPI 3.1 规范 | 带 OpenAPI 规范的 HTML 页面 |