跳转到正文
xclaude
文档目录

接口参考

本机 HTTP 接口、身份验证、终端控制与 WebSocket 事件。

以下是常用接口摘要，并非全部接口列表。接口会随版本变化；以对应版本的服务端实现为准。默认基址为 http://localhost:3333/api。

身份验证

未设置密码时只允许本机连接，远程请求返回 403。设置密码后，所有客户端都需登录。

  • GET /auth/status：查看登录要求。
  • POST /auth/login：提交密码，获取有效期一小时的 auth_token Cookie。
  • POST /auth/refresh：刷新登录。
  • POST /auth/logout：退出登录。

同一地址连续 5 次错误后最多锁定 15 分钟，返回 429。跨设备使用前，请先设置访问密码。

会话接口

  • GET /sessions：列出当前可见会话。
  • PUT /sessions/:id/title、remark、accent-color：修改名称、备注或颜色。
  • PUT /sessions/:id/remote-visible：修改远程可见性，仅本机可调用。
  • POST /sessions/:id/resume：恢复会话。
  • POST /sessions/:id/restart-terminal：重启终端，需提交 confirm: true。
  • POST /sessions/:id/fork、clone：分叉或克隆。
  • POST /sessions/:id/kill：强制结束，需提交 confirm: true。
  • DELETE /sessions/:id：关闭会话。
  • GET /sessions/:id/transcript：读取 Claude 会话记录。
  • POST /sessions/:id/summarize：生成摘要。

强制结束先向进程组发送 SIGTERM，约两秒后仍未退出则发送 SIGKILL，并关闭、取消固定该会话。摘要接口需要 context，可选 promptTemplate 或 custom_prompt；通过无工具的 Claude Haiku 运行，最多同时执行两个。

提示词队列

  • GET /sessions/:id/queue：读取完整队列。
  • PUT /sessions/:id/queue：更新队列。
  • POST /sessions/:id/queue/items：在末尾追加暂停状态的条目。
  • POST /sessions/:id/queue/resume：解除 Esc 引起的暂停。

终端接口

  • POST /terminals：创建，返回 { ok, terminalId }。
  • GET /terminals：列出终端。
  • DELETE /terminals/:id：关闭。
  • GET /terminals/:id/output：读取输出。
  • POST /terminals/:id/write：写入 { data }。

创建请求使用 workingDir 与 command，还可指定 sessionTitle、model、effortLevel、apiKey 和 enableOpsTerminal。SSH 配置包含主机、端口、用户名、认证方式和私钥路径；tmux 使用 useTmux、tmuxSession。最多 50 个会话、130 个终端，超过返回 429。

历史记录与搜索

  • GET /db/sessions、GET /db/sessions/:id：历史会话。
  • GET /db/projects：项目。
  • GET /db/search：搜索，支持 query 和 type=all|prompts|responses。
  • GET /db/prompts：提示词，kind 默认为 mine，也支持 cmd、agent 和 all 分类。

历史会话列表支持 query、精确 project、status、毫秒时间戳 dateFrom/dateTo 与 archived。默认排除归档；可用 true 或 all 调整。sortBy 支持 started_at（默认）、last_activity_at、project_name、status、total_prompts、total_tool_calls；sortDir 支持升序或降序。默认第 1 页，每页 50 条，最多 200 条。

WebSocket

连接 ws://localhost:3333。密码验证与 HTTP 相同，可通过 Cookie 或 Bearer 凭据连接。服务端也兼容查询参数令牌，但建议避免把凭据放入可能被记录的 URL。

  • 4001：身份验证失败。
  • 4003：来源不允许，或未设置密码时的远程连接。
  • 4004：消息速率超过每秒 100 条。
  • 单条消息最大 512 KB。

服务端事件

  • snapshot：会话、团队、序号及隐藏数量。
  • session_update、session_removed、team_update：状态变化。
  • terminal_ready、terminal_output、terminal_closed、terminal_geometry、terminal_cleared、terminal_error：终端事件；输出使用 Base64。
  • queue_update：完整队列。
  • hook_stats：钩子统计。

客户端事件

  • terminal_subscribe：订阅终端。
  • terminal_disconnect：取消订阅，终端继续运行。
  • terminal_input：向已订阅且有权限的可见终端输入。
  • terminal_resize：调整尺寸，不视为接管输入。
  • terminal_clear：清空缓冲区并同步给客户端。
  • replay：使用 sinceSeq 重放事件。

客户端重连等待从一秒增加到最多十秒。服务端保留最近 500 个事件供重放。

钩子接口

POST /hooks 仅允许本机、不需要登录，每个地址最多每秒 100 次。macOS/Linux 主要使用文件队列；HTTP 是备用通道。

GET /hooks/status、POST /hooks/install 和 POST /hooks/uninstall 用于管理钩子，安装参数包括 density、enabledClis。这些管理接口仍要求正常身份验证，并只允许本机。/hook-stats、/hook-stats/reset 与 /mq-stats用于诊断。

中央会话接口

/mcp/centrals、/mcp/activity、/mcp/tasks、/mcp/confirms 用于查看中央会话、活动、任务与确认卡片。活动列表默认 100 条，最多 500 条，可按中央会话筛选。

POST /mcp/confirm/:cardId 使用 decision: allow|deny；PUT /mcp/sessions/:id/hands-off 使用 on: boolean。这些接口供本机控制面板使用，普通远程请求返回 404，中央会话自身调用确认接口返回 403；功能关闭时相关接口返回 404。

原生中央会话通过本机 /mcp 端点和专用令牌使用工具。详细权限见中央会话。