XCClaw/docs/opencode-api.md

# OpenCode HTTP API 文档

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

## 启动服务

```bash
opencode serve --port 4096 --hostname 127.0.0.1
```

### 选项

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

### 认证

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

```bash
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`