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