XCClaw/opencode-api.md

OpenCode HTTP API 文档

本文档整理了 OpenCode HTTP Server 的所有 API 端点。

启动服务

opencode serve --port 4096 --hostname 127.0.0.1

选项

参数	描述	默认值
--port	监听端口	4096
--hostname	监听主机名	127.0.0.1
--cors	允许的浏览器来源	[]

认证

设置环境变量启用 HTTP 基本认证：

OPENCODE_SERVER_PASSWORD=your-password opencode serve

Global

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

Project

方法	路径	描述	响应
GET	/project	列出所有项目	Project[]
GET	/project/current	获取当前项目	Project

Path & VCS

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

Instance

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

Config

方法	路径	描述	响应
GET	/config	获取配置信息	Config
PATCH	/config	更新配置	Config
GET	/config/providers	列出 providers 和默认模型	{ providers: Provider[], default: { [key: string]: string } }

Provider

方法	路径	描述	响应
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	处理 OAuth 回调	boolean

Sessions

方法	路径	描述	备注
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	获取会话的 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

方法	路径	描述	备注
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

方法	路径	描述	响应
GET	/command	列出所有命令	Command[]

Files

方法	路径	描述	响应
GET	/find?pattern=<pat>	在文件中搜索文本	包含 path, lines, line_number, absolute_offset, submatches 的匹配对象数组
GET	/find/file?query=<q>	按名称查找文件和目录	string[] (paths)
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)

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

LSP, Formatters & MCP

方法	路径	描述	响应
GET	/lsp	获取 LSP 服务器状态	LSPStatus[]
GET	/formatter	获取格式化程序状态	FormatterStatus[]
GET	/mcp	获取 MCP 服务器状态	{ [name: string]: MCPStatus }
POST	/mcp	动态添加 MCP 服务器	body: { name, config }, 返回 MCP status object

Agents

方法	路径	描述	响应
GET	/agent	列出所有可用代理	Agent[]

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	显示通知 ({ title?, message, variant })	boolean
GET	/tui/control/next	等待下一个控制请求	Control request object
POST	/tui/control/response	响应控制请求 ({ body })	boolean

Auth

方法	路径	描述	响应
PUT	/auth/:id	设置认证凭据	body 必须匹配 provider schema, 返回 boolean

Events

方法	路径	描述	响应
GET	/event	Server-Sent Events 流	第一个事件是 server.connected, 然后是 bus events

Docs

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

查看 OpenAPI 规范

服务器发布 OpenAPI 3.1 规范，可通过以下地址查看：

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

例如：http://localhost:4096/doc