核心能力验证

技术研究 OpenCode API验证

验证 OpenCode Server 的核心功能、API 端点、配置选项与技术能力

API/接口分析

Server 启动命令

OpenCode 通过 opencode serve 命令启动一个无界面的 HTTP 服务器：

opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]

关键配置选项：

参数	描述	默认值
`--port`	监听端口	`4096`
`--hostname`	监听主机名	`127.0.0.1`
`--mdns`	启用 mDNS 服务发现	`false`
`--mdns-domain`	mDNS 服务域名	`opencode.local`
`--cors`	允许的浏览器源	`[]`（可多次指定）

认证机制

Server 支持通过环境变量配置 HTTP Basic Auth：

OPENCODE_SERVER_PASSWORD=your-password opencode serve

用户名默认为 opencode，可通过 OPENCODE_SERVER_USERNAME 覆盖
认证机制同时适用于 opencode serve 和 opencode web

API 端点概览

OpenAPI 规范

Server 发布 OpenAPI 3.1 规范，可通过以下地址访问：

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

例如 http://localhost:4096/doc，可在 Swagger Explorer 中查看完整的接口定义。

核心端点分类

Server 提供的 HTTP API 涵盖以下功能域：

1. 全局接口 (Global)

方法	路径	描述
`GET`	`/global/health`	获取服务器健康状态和版本
`GET`	`/global/event`	获取全局事件流（SSE）

2. 会话管理 (Sessions)

方法	路径	描述
`GET`	`/session`	列出所有会话
`POST`	`/session`	创建新会话
`GET`	`/session/:id`	获取会话详情
`DELETE`	`/session/:id`	删除会话
`POST`	`/session/:id/fork`	分叉会话
`POST`	`/session/:id/abort`	中止运行中的会话

3. 消息处理 (Messages)

方法	路径	描述
`GET`	`/session/:id/message`	列出会话中的消息
`POST`	`/session/:id/message`	发送消息并等待响应
`POST`	`/session/:id/prompt_async`	异步发送消息（不等待）
`POST`	`/session/:id/command`	执行斜杠命令
`POST`	`/session/:id/shell`	运行 Shell 命令

4. 文件操作 (Files)

方法	路径	描述
`GET`	`/find?pattern=<pat>`	在文件中搜索文本
`GET`	`/find/file?query=<q>`	按名称查找文件
`GET`	`/find/symbol?query=<q>`	查找工作区符号
`GET`	`/file?path=<path>`	列出文件和目录
`GET`	`/file/content?path=<p>`	读取文件内容

5. 配置管理 (Config)

方法	路径	描述
`GET`	`/config`	获取配置信息
`PATCH`	`/config`	更新配置
`GET`	`/config/providers`	列出提供商和默认模型

6. MCP & LSP

方法	路径	描述
`GET`	`/mcp`	获取 MCP 服务器状态
`POST`	`/mcp`	动态添加 MCP 服务器
`GET`	`/lsp`	获取 LSP 服务器状态

7. TUI 控制

方法	路径	描述
`POST`	`/tui/append-prompt`	追加文本到提示框
`POST`	`/tui/submit-prompt`	提交当前提示
`POST`	`/tui/execute-command`	执行命令

能力差距分析

原生支持情况

能力需求	是否支持	说明
无界面运行	✅ 完全支持	`opencode serve` 命令
HTTP API 访问	✅ 完全支持	OpenAPI 3.1 规范
远程访问	✅ 支持	通过 `--hostname 0.0.0.0`
认证保护	✅ 支持	HTTP Basic Auth
多客户端连接	✅ 支持	架构设计支持
CORS 配置	✅ 支持	`--cors` 参数
服务发现	✅ 支持	mDNS 协议
事件流	✅ 支持	SSE 端点

无需变通方案

OpenCode Server 的功能设计完整覆盖了常见的使用需求，无需额外的变通方案即可实现：

远程部署和访问
多客户端共享
程序化调用
IDE 集成
自动化脚本

验证方法

功能验证步骤

# 1. 启动 Server
opencode serve --port 4096 --hostname 0.0.0.0

# 2. 查看健康状态
curl http://localhost:4096/global/health

# 3. 查看 OpenAPI 文档
# 浏览器打开 http://localhost:4096/doc

# 4. 列出会话
curl http://localhost:4096/session

# 5. 带认证启动
OPENCODE_SERVER_PASSWORD=secret opencode serve

关键发现

OpenCode 采用客户端-服务器架构，这是理解 Server 功能的关键：

当你运行 opencode 时，它会启动 TUI 和一个 Server。TUI 是客户端，与 Server 通信。Server 暴露 OpenAPI 3.1 规范端点。

这种架构设计的意义在于：

解耦界面与逻辑：TUI、Web、IDE 插件都可以作为客户端
支持远程访问：Server 可部署在远程机器
程序化调用：任何 HTTP 客户端都可以调用 API