qwen-code 会话 Shell 权限策略全解析：默认禁用、显式开启与认证客户端绑定

qwen-code 会话 Shell 权限策略全解析默认禁用、显式开启与认证客户端绑定【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读qwen-code 的POST /session/:id/shell端点允许直接通过 daemon 执行 Shell 命令绕过 LLM 工具调用与常规 Agent 权限协商流程是一类权限极高的直连 Shell能力。为避免默认环境过度暴露该能力qwen-code 设计了 Session Shell Permission Policy会话 Shell 权限策略默认禁用、需要操作者显式开启、且必须在具备承载令牌或受信任回环trusted loopback权威的前提下生效每次调用还必须携带绑定到目标会话的客户端 ID。本文以 E2E 测试文档 为骨架结合 权限策略设计文档 与仓库源码实现完整讲解该策略的三种启动场景、四层防护校验链、错误契约以及自动化验证方法帮助读者掌握如何在自托管的qwen serve环境中安全地开启并调用直连会话 Shell。问题背景为什么直连 Shell 需要权限策略一个没有 Agent 介导的超级接口正常情况下Agent 执行 Shell 命令需要经过PermissionMediator等权限协商流程。而POST /session/:id/shell是 daemon 直接执行的 Shell 命令接口不经过 LLM 工具调用也不经过常规 Agent 权限介导流程。在权限策略落地之前这个端点是一个非严格non-strict的变更操作只要持有 daemon token 加一个 session id或者处于无 token 的回环loopback开发者默认环境就能触达。设计文档明确指出对一个直连 Shell 面而言这种授权过重——除非 daemon 操作者显式开启该能力且调用者证明自己附着于目标会话否则任何人都不应能够通过它执行 Shell 命令。完整背景见 权限策略设计文档。策略目标与非目标策略要达成的目标Goals默认禁用直连会话 Shell必须由操作者显式开启qwen serve --enable-session-shell开启前必须具备承载令牌bearer token配置或受信任回环操作者权威调用必须携带一个已注册在目标会话上的客户端 ID同一策略同时作用于 REST 路由、ACP HTTP 分发器和 bridge 执行汇execution sink常规 Agent Shell 工具审批与权限介导流程保持完全不变。明确的非目标Non-Goals不将直连 Shell 路由进PermissionMediator不改变提示词提交、提示词排队或 SDK 挂起提示词行为不新增 Shell 专属限流器不为开启开关新增环境变量别名。三种启动场景从默认关闭到完整可用E2E 文档用三个场景完整刻画了策略矩阵无认证默认启动、仅带令牌启动、带令牌并显式开启。三者分别对应完全不可用、能力可见但不可用、能力可见且可用三个状态。场景 1无 token 启动默认拒绝启动命令qwen serve # 回环绑定不传 --token也不设置 QWEN_SERVER_TOKEN此场景下必须满足以下断言GET /capabilities.features不得包含session_shell_commandACP initialize 响应的_meta.qwen.methods不得包含_qwen/session/shellPOST /session/:id/shell必须返回401 token_required。也就是说即使部署在 loopback 上只要没有承载令牌直连 Shell 从能力公告到实际调用三层全部被关闭。场景 2带 token 但未显式开启能力可见但禁用启动命令qwen serve --token token此场景下必须满足以下断言/capabilities.features不得包含session_shell_commandACP initialize不得公告_qwen/session/shell已认证的 REST Shell 调用必须返回session_shell_disabled。该场景证明了文档中操作者显式开启opt-in与承载认证是两个独立的必要条件仅有认证而缺少 opt-in能力同样被禁用。场景 3带 token 并显式开启完整可用启动命令qwen serve --token token --enable-session-shell此场景下必须满足以下断言/capabilities.features必须包含session_shell_commandACP initialize 必须公告_qwen/session/shellREST Shell 调用若缺少X-Qwen-Client-Id头必须返回client_id_requiredREST Shell 调用携带与会话绑定的客户端 ID 时必须真正执行命令并通过会话事件流式返回 Shell 输出。场景矩阵速查启动参数能力公告ACP 方法公告实际调用结果无--token、无--enable-session-shell无session_shell_command无_qwen/session/shell401 token_required--token t、无--enable-session-shell无session_shell_command无_qwen/session/shellsession_shell_disabled--token t、--enable-session-shell有session_shell_command有_qwen/session/shell缺客户端 ID 时client_id_required带会话绑定客户端 ID 时执行并流式输出核心机制一个布尔值贯穿三层生效开关的精确计算在 run-qwen-serve.ts 中runQwenServe只解析并 trim 一次承载令牌然后计算出一个有效的布尔值const trustedLoopbackMode isTrustedLoopbackMode({ loopbackBind: isLoopbackAddress(bindHostname), tokenConfigured: token ! undefined, requireAuth: optsIn.requireAuth true, }); const sessionShellCommandEnabled optsIn.enableSessionShell true (token ! undefined || trustedLoopbackMode);这个值随后被贯穿注入 bridge、REST app 和 ACP 分发器三处保证三层策略判断使用同一事实来源不会出现REST 已禁用但 ACP 仍可调之类的策略漂移。无效开启的显式告警如果操作者传了--enable-session-shell但既无 token 又非 trusted loopback策略并不会静默生效而是向 stderr 打印一条明确告警run-qwen-serve.tsqwen serve: --enable-session-shell ignored because no bearer token is configured. Set QWEN_SERVER_TOKEN or pass --token to enable direct session shell.这条告警对应设计文档中无承载认证的操作者 opt-in 无效的结论帮助操作者第一时间发现配置错误。令牌的 trim 语义与嵌入调用细节设计文档特别强调了两点实现细节runQwenServe对令牌做一次解析与 trim内嵌调用者直接调用createServeApp的进程用非空字符串检查判断令牌存在性使token: 与无 token行为一致——无论对严格变更门禁还是对 Shell 能力公告都如此避免空字符串令牌意外获得权限。REST 路径严格门禁下的四层防护链REST 路由使用mutate({ strict: true })开启严格模式server/error-response.ts 中集中定义了错误码。请求在进入 handler 之前、之后依次经历四层检查操作者权威门禁在无 token 的受信任回环主监听器上严格门禁直接放行请求而在无 token 的非受信任内嵌场景handler 尚未运行就返回401 token_required能力启用检查权威校验通过后handler 若发现 Shell 能力未启用返回403且code/errorKind: session_shell_disabled客户端 ID 检查随后要求X-Qwen-Client-Id头缺失时返回403 client_id_required命令体校验与会话绑定校验校验命令体合法性再委托给 bridge 完成会话存在性与客户端绑定校验400 invalid_client_id/404 SessionNotFoundError。ACP 路径公告过滤 禁用时静默拒绝ACP HTTP 分发器在 acp-http/dispatch.ts 中实现方法常量定义为_qwen/session/shellconst SESSION_SHELL_METHOD \${QWEN_METHOD_NS}session/shell见 dispatch.ts兼容旧客户端分发器保留_qwen/session/shell的分发能力但仅在有效策略开启时才把它加入 initialize 的_qwen.methods列表过滤逻辑为sessionShellCommandEnabled || method ! SESSION_SHELL_METHODdispatch.ts禁用时ACP 调用返回稳定的RPC.INVALID_PARAMSJSON-RPC 错误data.errorKind: session_shell_disableddispatch.ts并且不记录命令、不调用 bridge——避免敏感命令内容落入日志启用时调用仍要求连接拥有该会话且必须使用 bridge 盖章的会话绑定客户端 ID。Bridge 执行汇最后一道纵深防御bridge 在 bridge.ts 的executeShellCommand()中强制执行最后一道纵深防御检查检查顺序为能力未开启抛出SessionShellDisabledErroropts.sessionShellCommandEnabled ! true缺少客户端 ID抛出SessionShellClientRequiredError未知会话抛出SessionNotFoundError客户端 ID 未绑定会话由resolveTrustedClientId解析失败走既有invalid_client_id映射。只有全部通过后bridge 才发布 Shell 事件、执行命令、写 Shell 历史。作为纵深防御即使上层 REST 或 ACP 层出现配置遗漏bridge 汇仍能拦截未授权的直连 Shell 执行。错误契约汇总REST 层条件HTTP 状态code / errorKind无 token 的非受信任内嵌401token_required能力禁用403session_shell_disabled缺少客户端 ID403client_id_required客户端 ID 畸形或未绑定400invalid_client_id会话不存在404SessionNotFoundError既有映射ACP 层条件JSON-RPC 错误data.errorKind能力禁用RPC.INVALID_PARAMSsession_shell_disabled缺少会话绑定客户端 IDRPC.INVALID_PARAMSclient_id_required会话未拥有 / 客户端 ID 非法既有 JSON-RPC 映射—兼容性SDK 客户端的行为变化权限策略对 SDK 调用方有一个直接且重要的影响DaemonSessionClient.shellCommand()继续可用——只要 daemon 被显式开启且具备操作者权威。原因是会话客户端本身携带会话绑定的客户端 ID天然满足校验裸调用DaemonClient.shellCommand(sessionId, command)必须显式传入opts.clientId否则会收到client_id_required。这意味着任何基于 SDK 构建直连 Shell 能力的集成方都必须改为会话绑定模型而非凭 token 即可执行。自动化验证聚焦检查与最终门禁聚焦的自动化检查针对 bridge、REST、ACP transport、serve 启动与命令解析的聚焦测试cd packages/acp-bridge npx vitest run src/bridge.test.ts cd packages/cli npx vitest run src/serve/server.test.ts src/serve/acpHttp/transport.test.ts src/commands/serve.test.tsbridge.test.ts 覆盖 bridge 执行汇的启用/禁用、客户端 ID 缺失、会话绑定等场景可检索sessionShellCommandEnabled: true的测试夹具server.test.ts 覆盖能力公告矩阵包括默认省略session_shell_command见omits \session_shell_command by default、受信任回环开启后公告、非受信任内嵌省略、带 token 开启后公告等用例transport.test.ts 覆盖 ACP 分发器的session_shell_disabled/client_id_required错误映射serve.test.ts 覆盖命令解析与启动参数传递。最终验证门禁npm run build npm run typecheck该验证覆盖了什么、不覆盖什么已证明What This Proves默认 daemon 不暴露直连会话 Shell无承载认证时的操作者 opt-in 无效已认证的 opt-in 在 REST 与 ACP 两侧公告能力保持一致调用仍需要绑定目标会话的客户端 ID。未证明What This Does Not Prove——明确的能力边界不验证提示词队列背压prompt queue backpressure不验证常规 Agent 发起的 Shell 工具审批行为该策略刻意不改动PermissionMediator流程不新增或验证 Shell 专属限流。设计演进受信任回环权威的补充权限策略设计文档顶部有重要修订说明该设计被 Trusted Loopback Full API 设计 修订——无 token 的回环主监听器现在可以持有操作者权威而无需被标记为承载认证。这解释了sessionShellCommandEnabled计算中trustedLoopbackMode一极的来源在受信任回环上--enable-session-shell即使不配 token 也能生效而在非受信任的嵌入场景中则严格返回401 token_required。关键源码索引关注点路径CLI 参数定义--enable-session-shellpackages/cli/src/commands/serve.ts生效布尔值计算与告警packages/cli/src/serve/run-qwen-serve.tsACP 方法过滤与错误映射packages/cli/src/serve/acp-http/dispatch.tsREST 错误码定义packages/cli/src/serve/server/error-response.ts能力特征定义packages/cli/src/serve/capabilities.tsBridge 纵深防御packages/acp-bridge/src/bridge.tsBridge 选项类型packages/acp-bridge/src/bridgeOptions.ts设计文档docs/design/2026-06-12-session-shell-permission-policy.mdE2E 验证文档.qwen/e2e-tests/session-shell-permission-policy.md安全实践要点综合以上分析在自托管qwen serve时启用直连会话 Shell 的安全底线是默认保持关闭不要移除--enable-session-shell的默认false语义必须显式开启任何情况下只应通过--enable-session-shell显式 opt-in认证是前置条件要么配置--token/QWEN_SERVER_TOKEN要么确保处于受信任回环模式否则 opt-in 会被忽略并打印告警调用必须会话绑定所有直连 Shell 调用都要携带目标会话注册的X-Qwen-Client-IdSDK 层使用DaemonSessionClient.shellCommand()或显式传入opts.clientId保持审计能力在 ACP 禁用分支中命令不被记录、不触达 bridge这是刻意设计——防止禁用状态下的命令内容泄入日志运维审计应依赖 bridge 执行汇在真正执行时发布的 Shell 事件与历史写入。这套默认禁用 显式开启 认证前置 会话绑定 三层一致性 纵深防御的策略组合为高权限直连 Shell 面提供了清晰的权限最小化基线同时完整保留了常规 Agent Shell 审批流程不受影响。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考