--- title: 服务器 description: 通过 HTTP 与 opencode 服务器交互。 --- import config from "../../../../config.mjs" export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts` `opencode serve` 命令运行一个无界面的 HTTP 服务器，暴露一个 OpenAPI 端点供 opencode 客户端使用。 --- ### 用法 ```bash opencode serve [--port ] [--hostname ] [--cors ] ``` #### 选项 | 标志 | 描述 | 默认值 | | --------------- | --------------------- | ---------------- | | `--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](/docs/sdk)。 :::tip 使用 opencode 服务器以编程方式与 opencode 交互。 ::: 这种架构让 opencode 支持多个客户端，并允许你以编程方式与 opencode 交互。 你可以运行 `opencode serve` 来启动一个独立的服务器。如果你已经在运行 opencode TUI，`opencode serve` 会启动一个新的服务器。 --- #### 连接到现有服务器 当你启动 TUI 时，它会随机分配端口和主机名。你也可以传入 `--hostname` 和 `--port` [标志](/docs/cli)，然后用它来连接对应的服务器。 [`/tui`](#tui) 端点可用于通过服务器驱动 TUI。例如，你可以预填充或运行一个提示词。此方式被 OpenCode [IDE](/docs/ide) 插件所使用。 --- ## 规范 服务器发布了一个 OpenAPI 3.1 规范，可在以下地址查看： ``` http://:/doc ``` 例如，`http://localhost:4096/doc`。使用该规范可以生成客户端或检查请求和响应类型，也可以在 Swagger 浏览器中查看。 --- ## API opencode 服务器暴露以下 API。 --- ### 全局 | 方法 | 路径 | 描述 | 响应 | | ----- | ---------------- | ------------------------ | ------------------------------------ | | `GET` | `/global/health` | 获取服务器健康状态和版本 | `{ healthy: true, version: string }` | | `GET` | `/global/event` | 获取全局事件（SSE 流） | 事件流 | --- ### 项目 | 方法 | 路径 | 描述 | 响应 | | ----- | ------------------ | ------------ | --------------------------------------------- | | `GET` | `/project` | 列出所有项目 | Project[] | | `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[]`, default: { [key: string]: string } }` | --- ### 提供商 | 方法 | 路径 | 描述 | 响应 | | ------ | -------------------------------- | ----------------------- | ----------------------------------------------------------------------------------- | | `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` | --- ### 会话 | 方法 | 路径 | 描述 | 说明 | | -------- | ---------------------------------------- | -------------------------- | --------------------------------------------------------------------------------- | | `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` | --- ### 消息 | 方法 | 路径 | 描述 | 说明 | | ------ | --------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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[]`}` | --- ### 命令 | 方法 | 路径 | 描述 | 响应 | | ----- | ---------- | ------------ | --------------------------------------------- | | `GET` | `/command` | 列出所有命令 | Command[] | --- ### 文件 | 方法 | 路径 | 描述 | 响应 | | ----- | ------------------------ | -------------------- | ----------------------------------------------------------------------------------- | | `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"` 仅返回文件） --- ### 工具（实验性） | 方法 | 路径 | 描述 | 响应 | | ----- | ------------------------------------------- | ---------------------------------- | -------------------------------------------- | | `GET` | `/experimental/tool/ids` | 列出所有工具 ID | ToolIDs | | `GET` | `/experimental/tool?provider=

&model=` | 列出指定模型的工具及其 JSON Schema | ToolList | --- ### LSP、格式化器和 MCP | 方法 | 路径 | 描述 | 响应 | | ------ | ------------ | ------------------- | -------------------------------------------------------- | | `GET` | `/lsp` | 获取 LSP 服务器状态 | LSPStatus[] | | `GET` | `/formatter` | 获取格式化器状态 | FormatterStatus[] | | `GET` | `/mcp` | 获取 MCP 服务器状态 | `{ [name: string]: `MCPStatus` }` | | `POST` | `/mcp` | 动态添加 MCP 服务器 | 请求体：`{ name, config }`，返回 MCP 状态对象 | --- ### 代理 | 方法 | 路径 | 描述 | 响应 | | ----- | -------- | ------------------ | ------------------------------------------- | | `GET` | `/agent` | 列出所有可用的代理 | Agent[] | --- ### 日志 | 方法 | 路径 | 描述 | 响应 | | ------ | ------ | ----------------------------------------------------------- | --------- | | `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 页面 |