开发与生态

服务器

通过 HTTP 与 opencode 服务器交互。

官方简体中文源 / server.mdx / 固定提交 8c81f9a4

opencode serve 命令运行一个无界面的 HTTP 服务器，暴露一个 OpenAPI 端点供 opencode 客户端使用。

用法

bash
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 可以多次传递：

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。

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

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

连接到现有服务器

当你启动 TUI 时，它会随机分配端口和主机名。你也可以传入 --hostname 和 --port 标志，然后用它来连接对应的服务器。

/tui 端点可用于通过服务器驱动 TUI。例如，你可以预填充或运行一个提示词。此方式被 OpenCode IDE 插件所使用。

规范

服务器发布了一个 OpenAPI 3.1 规范，可在以下地址查看：

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

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

API

opencode 服务器暴露以下 API。

全局

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

项目

方法 路径 描述 响应
GET /project 列出所有项目 [Project[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)
GET /project/current 获取当前项目 Project

路径和 VCS

方法 路径 描述 响应
GET /path 获取当前路径 Path
GET /vcs 获取当前项目的 VCS 信息 VcsInfo

实例

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

配置

方法 路径 描述 响应
GET /config 获取配置信息 Config
PATCH /config 更新配置 Config
GET /config/providers 列出提供商和默认模型 { providers: [Provider[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts), default: { [key: string]: string } }

提供商

方法 路径 描述 响应
GET /provider 列出所有提供商 { all: [Provider[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts), default: {...}, connected: string[] }
GET /provider/auth 获取提供商认证方式 { [providerID: string]: [ProviderAuthMethod[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts) }
POST /provider/{id}/oauth/authorize 使用 OAuth 授权提供商 ProviderAuthAuthorization
POST /provider/{id}/oauth/callback 处理提供商的 OAuth 回调 boolean

会话

方法 路径 描述 说明
GET /session 列出所有会话 返回 [Session[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)
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[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)
GET /session/:id/todo 获取会话的待办事项列表 返回 [Todo[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)
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[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)
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

消息

方法 路径 描述 说明
GET /session/:id/message 列出会话中的消息 查询参数：limit?，返回 { info: Message, parts: [Part[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)}[]
POST /session/:id/message 发送消息并等待响应 请求体：{ messageID?, model?, agent?, noReply?, system?, tools?, parts }，返回 { info: Message, parts: [Part[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)}
GET /session/:id/message/:messageID 获取消息详情 返回 { info: Message, parts: [Part[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)}
POST /session/:id/prompt_async 异步发送消息（不等待响应） 请求体：与 /session/:id/message 相同，返回 204 No Content
POST /session/:id/command 执行斜杠命令 请求体：{ messageID?, agent?, model?, command, arguments }，返回 { info: Message, parts: [Part[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)}
POST /session/:id/shell 运行 shell 命令 请求体：{ agent, model?, command }，返回 { info: Message, parts: [Part[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)}

命令

方法 路径 描述 响应
GET /command 列出所有命令 [Command[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)

文件

方法 路径 描述 响应
GET /find?pattern=<pat> 在文件中搜索文本 包含 path、lines、line_number、absolute_offset、submatches 的匹配对象数组
GET /find/file?query=<q> 按名称查找文件和目录 string[]（路径）
GET /find/symbol?query=<q> 查找工作区符号 [Symbol[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)
GET /file?path=<path> 列出文件和目录 [FileNode[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)
GET /file/content?path= 读取文件 FileContent
GET /file/status 获取已跟踪文件的状态 [File[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)

/find/file 查询参数

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

工具（实验性）

方法 路径 描述 响应
GET /experimental/tool/ids 列出所有工具 ID ToolIDs
GET /experimental/tool?provider=&model=<m> 列出指定模型的工具及其 JSON Schema ToolList

LSP、格式化器和 MCP

方法 路径 描述 响应
GET /lsp 获取 LSP 服务器状态 [LSPStatus[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)
GET /formatter 获取格式化器状态 [FormatterStatus[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)
GET /mcp 获取 MCP 服务器状态 { [name: string]: MCPStatus }
POST /mcp 动态添加 MCP 服务器 请求体：{ name, config }，返回 MCP 状态对象

代理

方法 路径 描述 响应
GET /agent 列出所有可用的代理 [Agent[]](https://github.com/anomalyco/opencode/blob/8c81f9a40b0eb8ccef911a033ea685e3233ad461/packages/sdk/js/src/gen/types.gen.ts)

日志

方法 路径 描述 响应
POST /log 写入日志条目。请求体：{ 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 显示提示消息（{ title?, message, variant }） boolean
GET /tui/control/next 等待下一个控制请求 控制请求对象
POST /tui/control/response 响应控制请求（{ body }） boolean

认证

方法 路径 描述 响应
PUT /auth/:id 设置认证凭据。请求体必须匹配提供商的数据结构 boolean

事件

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

文档

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

官方原文

本页来自 OpenCode 官方简体中文文档的固定版本，并转换为 xueai 静态页面。内容以官方持续更新的页面为准。

内容授权与修改

官方文档源代码采用 MIT License。本站保留许可证、固定提交号和修改说明，不代表 OpenCode 或 anomalyco 对本站背书。

MIT License，来源和修改说明