Qwen Code Daemon（qwen serve）系列文档
June 12, 2026 · View on GitHub
Qwen Code 的 HTTP daemon 运行时：一个长驻进程把一个 workspace 的 N 个 AI session 同时服务给多种客户端（web / 桌面 / IDE / SDK / MCP）。本系列覆盖架构、API、部署、安全与使用指南。
当前状态（2026-06-13）：daemon 功能集已合入 main（PR#4490），随 v0.18.0 正式版发布（2026-06-12，#5050）。开发在
daemon_mode_b_main长期 integration 分支进行，周期性反向 merge 回 main。
一、daemon 是什么
$\text{text} ┌─────────────────────────────────────────┐ │ \text{qwen} \text{serve} \text{daemon} │ │ 1 \text{process} = 1 \text{workspace} \times \text{N} \text{session} │ │ \text{HttpAcpBridge} + \text{EventBus} + 内嵌一个 │ │ \text{qwen} --\text{acp} \text{child}（\text{N} \text{session} 多路复用） │ └────────────────────┬────────────────────┘ │ ┌────────────┬────────────┬────────┴───────┬────────────────┬───────────┐ ▼ ▼ ▼ ▼ ▼ ▼ \text{REST} + \text{SSE} \text{ACP} \text{HTTP} \text{ACP} \text{WebSocket} \text{MCP} \text{stdio} 官方桌面 \text{app} \text{ACP} \text{stdio} /\text{session}/* /\text{acp} \text{WS} /\text{acp} \text{qwen}-\text{serve}- \text{packages}/ （\text{in}-\text{process} /\text{workspace}/* (#4472) (#4773) \text{bridge} (#4555) \text{desktop} \text{TUI} 直连） │ │ │ (#3778) \text{web}-\text{shell} \text{Zed} / \text{Goose} 等 \text{Qoder} / \text{Claude} \text{webui} + \text{SDK} \text{ACP}-\text{native} \text{client} \text{Desktop} / \text{Cursor} \text{channels} （41 个 \text{\_qwen}/* \text{method}，#4827 达 \text{REST} \text{parity}） $
普通 qwen 是"一个终端进程 = 一个会话"。`qwen serve$ 把会话搬进一个长驻 \text{headless} \text{daemon}：
- 1 \text{daemon} = 1 \text{workspace} \times \text{N} \text{session}——启动时绑定 \text{cwd} 为唯一 \text{workspace}，\text{N} 个 \text{session} 在 \text{daemon} 内多路复用；多 \text{workspace} = 多 \text{daemon} 进程（\text{OS} 进程级隔离，\text{systemd} / \text{docker} / \text{K8s} 天然对应）
- 多客户端同时接入——同一个 \text{session} 可以被浏览器（\text{web}-\text{shell}）、桌面 \text{app}、\text{IDE}、\text{SDK}、甚至另一台机器上的客户端同时观看与操作；事件经 \text{SSE}/\text{WebSocket} \text{fan}-\text{out}，\text{prompt} 按 \text{FIFO} 串行
- 三套 \text{northbound} 协议 + \text{MCP} 桥——自有 \text{REST}+\text{SSE}、标准 \text{ACP}（\text{HTTP} 与 \text{WebSocket} 两种 \text{transport}），以及把 \text{daemon} 包装成 \text{MCP} \text{server} 的 $qwen-serve-bridge`；qwen-code 是目前唯一同时打 ACP + MCP 两个开放标准的 daemon（Claude/Cursor 闭门，Goose 仅 ACP）
二、关键能力一览
| 能力 | 说明 | 来源 |
|---|---|---|
| 非阻塞 prompt | POST /session/:id/prompt 立即返回 202 {promptId}，结果经 SSE turn_complete/turn_error 按 promptId 关联 | #4585 |
| 事件流 + 断线重放 | SSE ring buffer + Last-Event-ID 重连重放；ring 淘汰时推 state_resync_required 强制 client 重同步 | #4237 / #4360 |
| 多 client 权限投票 | PermissionMediator 4 策略：first-responder（默认）/ designated / consensus / local-only | #4335 |
| MCP 连接池 | workspace 级共享 transport pool，N session 复用同一 MCP server 连接，预算封顶 | #4336 |
| 文件安全边界 | workspace 根限定 + symlink 逃逸拒绝 + 原子写（temp+rename）+ content-hash 前置条件 | #4250 / #4280 |
| OAuth 设备流代理 | RFC 8628 device-flow 由 daemon 代办，凭证不过 client；BrandedSecret 四路脱敏 | #4255 |
| 认证与防护 | Bearer token + --require-auth 写路由门禁；0.0.0.0 无 token 拒绝启动；--allow-origin CORS 白名单；--rate-limit 令牌桶 | #3889 / #4236 / #4527 / #4861 |
| 服务端 shell | POST /session/:id/shell 直接执行 ! 命令（不经 LLM），输出流式回放并注入会话历史 | #4576 |
| 会话生命周期 | load / resume / branch / detach / rewind snapshots / recap / stats / context-usage / tasks 快照 | 见 §03 |
| 可观测性 | OTel tracing（prompt lifecycle / tool spans / per-prompt traceId）+ daemon 文件日志 + errorKind 封闭错误分类 | #4321 / #4559 |
| 配置热重载 | POST /workspace/reload 统一 settings 重载，只刷真正变化的 key | #4965 |
三、9 个核心架构决策
| # | 决策 | 选择 |
|---|---|---|
| 1 | session 跨 client 共享 | 默认 `sessionScope: 'single'$，可共享 |
| 2 | 状态进程模型 | 1 \text{daemon} = 1 \text{workspace} \times \text{N} \text{session}（\text{OS} 进程级隔离） |
| 3 | \text{MCP} 生命周期 | \text{workspace} 级共享 \text{transport} \text{pool} |
| 4 | \text{FileReadCache} | \text{per}-\text{session} 严格私有 |
| 5 | \text{Permission} \text{flow} | 4 策略 \text{mediator}（\text{first}-\text{responder} 默认） |
| 6 | 多 \text{client} 并发 | 同 \text{session} \text{prompt} \text{FIFO} 串行 + 事件 \text{fan}-\text{out} |
| 7 | 部署模式 | **\text{Mode} \text{B}（\text{headless} $qwen serve）主线**；Mode A（qwen --serve` 带 TUI）暂停 |
| 8 | server / client / runtime 边界 | 4 层分离，acp-bridge 独立包 |
| 9 | northbound transport | dual additive：自有 REST+SSE 与标准 ACP 共存 |
每条决策的备选项与依据见 §02 Architectural Decisions。
四、文档地图
| # | 文档 | 内容 | 适合 |
|---|---|---|---|
| 01 | Overview | 术语、架构图、双部署模式、资源经济性 | 第一次了解 daemon |
| 02 | Architectural Decisions | 9 个核心决策的备选项与取舍依据 | 理解"为什么这样设计" |
| 03 | HTTP API & Protocol | 完整路由参考 + SSE 事件 + ACP transport + capability 协商 | 写 client / 接 API |
| 04 | Deployment & Client | 部署拓扑、多 client 协调、远端接入 | 设计客户端 / 拓扑选型 |
| 05 | Security & Permission | 三层权限模型、认证、多租户边界 | 安全评估 / 企业部署 |
| 06 | Roadmap & Ecosystem | 已落地里程碑（压缩史）、进行中、远期方向、业界对照 | 了解进展与方向 |
| 07 | User Guide | 启动 flag、安全配方、部署 shape、客户端接入、故障排查 | 直接上手用 |
阅读路径
| 你想 | 读 | 时间 |
|---|---|---|
| 立刻跑起来 | 07 快速上手 + 客户端接入 | ~10 min |
| 快速理解架构 | 本页 → 01 → 02 | ~20 min |
| 写一个 client / 集成 | 03 → 04 → 07 | ~1 h |
| 安全 / 多租户评估 | 05 → 07 安全配方 | ~40 min |
| 全面了解 | 01 → 07 顺序读 | ~2 h |
五、团队分工（upstream）
| 方向 | 主力 |
|---|---|
| server 架构 / 路由 / 可靠性 | doudouOUC |
| SDK / ACP transport / 跨 client 同步 | chiga0 |
| web-shell（React web client） | ytahdn |
| MCP 桥（qwen-serve-bridge） | jifeng |
| review / 架构守门 | wenshao（maintainer） |
六、进行中与后续
- backlog（#4514）：pair token + per-client 撤销、
loadSession/resume转正（去unstable_前缀）、branch/rewind HTTP 化、multi-daemon 协调等 - side-channel 协调（#4511）：A2 / A5 两项设计未落地
- TUI daemon-client adapter：本地 TUI 接 daemon 的适配层（scope 仍在收敛；本地 TUI 默认 in-process 直连不变）
- 容器化部署模板：systemd / launchd / nohup 模板已有，Docker / K8s 参考件待补
- 相邻方向：dynamic workflows（LLM 写编排脚本 fan-out）走 in-process tool 路线、不依赖 daemon，见 Claude Code Dynamic Workflows Deep-Dive
实施跟踪：#4175（rollout tracker）。
免责声明：本系列由 codeagents 项目维护，基于源码与 PR 跟踪写成，不代表 Qwen Code 团队官方路线图。daemon 处于 preview 阶段，API（尤其
unstable_前缀路由）可能继续变化。截至 2026-06-12。