Skip to Content
开发者指南Daemon REST API 参考

Daemon REST API 参考

这是运行 qwen serve --no-web 并提供自有 UI 的集成所使用的公共 REST/SSE 接口。请先阅读集成指南，然后使用本页面进行端点发现，并参考 HTTP 协议参考 了解详细的生命周期语义。

OpenAPI

经过整理的 25 个操作契约以 OpenAPI 3.1 JSON  形式提供。将该 URL 导入兼容 OpenAPI 的渲染器、客户端生成器或验证工具。已提交的 JSON 是下方索引操作的便携接口契约，并在 CI 中根据指南、协议标题和已注册路由进行了验证。

本索引涵盖 daemon REST 接口中经过整理的核心子集，而非全部内容。索引之外包括第一方 Web Shell 路由、条件内部表面以及其他公开但非核心的路由：文件变更、工作区注册、会话组织与 generation，以及工作区 MCP、skill 和 provider 等。这些表面由各自的能力标签进行通告；HTTP 协议参考 记录了会话、工作区状态和文件表面，MCP 服务器管理、认证提供者和设备流登录则由 daemon 认证与安全说明 覆盖。它们不在本契约范围内，但并未被弃用。

阅读索引

  • Capability 是在 GET /capabilities 中需要检查的功能标签。破折号表示该操作没有专属的功能标签；需要支持较旧 daemon 构建版本的客户端应处理 404。
  • Scope 指明哪个运行时拥有该操作。process-global 读取 daemon 全局状态，selected-runtime 使用请求的工作区选择，persisted-workspace 解析持久化会话存储，live-session-owner 通过实时会话进行路由，legacy-primary 始终定位 daemon 的主工作区。GET /session/:id/export 固定为主工作区：它仅在托管内部运行时中解析，然后回退到主工作区。
  • 本索引中的所有操作在 v1 REST 契约中均为 stable。已弃用的 unstable_session_resume 能力名称仅为别名；请使用 session_resume 作为稳定的 resume 路由。

Discovery

OperationCapabilityScopeTypeScript SDK
GET /healthhealthprocess-globalDaemonClient.health
GET /capabilitiescapabilitiesprocess-globalDaemonClient.capabilities

会话生命周期

OperationCapabilityScopeTypeScript SDK
POST /sessionsession_createselected-runtimeDaemonClient.createOrAttachSession
POST /session/:id/loadsession_loadselected-runtimeDaemonClient.loadSession
POST /session/:id/resumesession_resumeselected-runtimeDaemonClient.resumeSession
POST /session/:id/heartbeatclient_heartbeatlive-session-ownerDaemonClient.heartbeat
PATCH /session/:id/metadatasession_metadatalive-session-ownerDaemonClient.updateSessionMetadata
POST /session/:id/modelsession_set_modellive-session-ownerDaemonClient.setSessionModel
DELETE /session/:idsession_closelive-session-ownerDaemonClient.closeSession

提示与事件

OperationCapabilityScopeTypeScript SDK
GET /session/:id/statussession_statuslive-session-ownerDaemonClient.sessionStatus
POST /session/:id/promptsession_promptlive-session-ownerDaemonClient.promptNonBlocking
POST /session/:id/cancelsession_cancellive-session-ownerDaemonClient.cancel
GET /session/:id/eventssession_eventslive-session-ownerDaemonClient.subscribeEvents
GET /session/:id/transcriptsession_transcriptpersisted-workspaceDaemonClient.getSessionTranscriptPage
GET /session/:id/contextsession_contextlive-session-ownerDaemonClient.sessionContext
GET /session/:id/exportsession_exportlegacy-primaryDaemonClient.exportSession
GET /session/:id/pending-prompts—live-session-ownerDaemonClient.getPendingPrompts

POST /session/:id/prompt 在提示进入队列时返回 202，而非 Agent 完成时。请先订阅，然后通过 promptId 关联 turn_complete 或 turn_error。

权限

OperationCapabilityScopeTypeScript SDK
POST /session/:id/permission/:requestIdsession_permission_votelive-session-ownerDaemonClient.respondToSessionPermission
POST /permission/:requestIdpermission_votelegacy-primaryDaemonClient.respondToPermission

新的多工作区集成应始终使用会话作用域路由。旧版路由对属于另一个运行时的请求可能返回与已解决投票相同的 404。

只读工作区上下文

OperationCapabilityScopeTypeScript SDK
GET /workspace/tools—legacy-primaryDaemonClient.workspaceTools
GET /fileworkspace_file_readlegacy-primaryDaemonClient.readWorkspaceFile
GET /file/bytesworkspace_file_byteslegacy-primaryDaemonClient.readWorkspaceFileBytes
GET /statworkspace_file_readlegacy-primaryDaemonClient.fileStat
GET /listworkspace_file_readlegacy-primaryDaemonClient.dirList
GET /globworkspace_file_readlegacy-primaryDaemonClient.glob

这些单一路由定位主工作区。暴露多个已注册工作区的集成应使用完整协议中记录的工作区限定对应路由，并预检 workspace_qualified_rest_core。

通用协议规则

  • 使用 Authorization: Bearer <token> 对常规路由进行认证。默认的本地回环 /health 探测可以豁免；非本地回环绑定则不可豁免。
  • 当 create/load 响应提供了 X-Qwen-Client-Id 时发送该头。它是一个附加和归因标识符，而非终端用户安全主体。
  • 将错误体视为附加信息。主要根据 HTTP 状态码以及稳定的 code 或 errorKind（如果存在）进行分支处理。
  • 保留 SSE 响应头并禁用代理缓冲。当 daemon 提供了 epoch 时，同时使用 Last-Event-ID 和 X-Qwen-Event-Epoch 进行恢复。
  • 工作区信任边界不是租户隔离。当安全主体或进程级故障边界必须独立时，请运行独立的 daemon。
Last updated on
REST API 集成指南qwen serve HTTP 协议