Web Shell 与远程访问

连接浏览器或手机，配置跨域、Local Control、PWA 与语音入口。

This page has not been translated into English yet. The original Chinese version is shown below.

Web Shell 默认与 daemon API 共用一个 origin，入口是监听地址根路径。--open 在可用时自动打开浏览器，--no-web 则移除内置界面；后者还让 Local Control 无法启用，并不注册依赖 Web Shell 的 Live 路由。

浏览器连接

qwen serve --open

普通 loopback 下该命令仍是无 token 模式；需要认证的便捷启动见open-with-auth。远程可显式选择监听地址：

qwen serve --hostname 0.0.0.0

没有令牌来源时会生成并打印临时 bearer。通配地址启动显示本机接口得到的局域网地址，不自动发现公网 IP，也不保证防火墙或 NAT 可达。接口筛选基于名称启发式，不能保证排除所有 VPN 或容器网桥。

Web Shell 可在连接界面或 Daemon Status 选择另一 daemon 的 origin 和 token。凭据按 tab 与 daemon origin 分开保存，不复用到别的 daemon；切换会刷新页面，侧栏一次只显示所选 daemon 的工作区。Add workspace 的绝对路径属于远程 daemon 主机，不是浏览器本机。

未知 ?daemon= 地址要经连接界面确认后才联系。跨 origin 不提供浏览器本地文件桥接；HTTPS 页面也不能连接 HTTP daemon。

Origin 与端口

内置界面直接同源的 HTTP 请求通常不需 allow-origin。来自其他页面的请求，应在 daemon 上列出精确 origin，例如：

qwen serve --hostname 0.0.0.0 \
  --allow-origin http://localhost:4170

WebSocket 终端和语音另有门禁，远端浏览器通常也需要明确 allow-origin。值是完整 origin，不带路径、查询或尾斜杠；不支持子域名通配。Origin: null 即使在 * 下也被拒绝。loopback 的 * 或远程 HTTP(S) origin 配置需有 token，浏览器扩展 origin 另有本机兼容路径。

daemon 不信任 forwarded headers 来认定同源。TLS 终止代理，或重写 Host 的 HTTP 代理，需明确允许浏览器实际 origin；单纯非 loopback 端口映射不因监听端口不同而失配。loopback 的 Host 防重绑定门禁则只接受本监听端口，ssh -L 8080:localhost:4170 会被拒绝，allow-origin 也不能覆盖；应使用同端口转发或明确采用相应非 loopback 部署。

Mobile access 邀请绑定生成请求的 scheme 和 Host。TLS 代理后可能仍生成 http 邀请，导致手机 https 页面交换失败；改从 daemon 直接地址配对，或在手机输入 token。

Local Control

--local-control 在选定的私有 IPv4 接口共享 Web Shell，使用 daemon 管理、可撤销的配对令牌和 QR，并尽力阻止系统睡眠。多候选地址时用 --local-control-address 选择。

它可与 token、allow-origin、port 0 组合，但与 no-web 和非默认 hostname 冲突。Local Control 不让普通 HTTP 局域网地址变成浏览器安全上下文，语音等能力仍需TLS。

安装为 PWA

支持的浏览器可选择 Install app 或 Add to Home Screen。安装地址始终是服务器根路径，不保存当前 session、workspace 或 URL token；独立窗口可能需要重新输入凭据。

service worker 只缓存带内容哈希的构建资源，图标和 manifest 重新验证。API、SSE、带认证 header 的请求走网络，不缓存会话、文件或凭据。服务器离线时，在 worker 已接管页面的前提下展示重试页；不提供离线工作、关闭后的 Web Push 或通知。

远端需可信 HTTPS，局域网纯 HTTP 不启用 service worker。更新可立即激活但不强制刷新已开页面；嵌入式库消费者不注册这个 worker。运行时品牌定制不改安装元数据里的内置身份。

Qwen Live

实验性 Live 通过 Web Shell 的 /live/web WebSocket，让浏览器充当麦克风与扬声器，需要 HTTPS 或 localhost。macOS 原生 Qwen Live Host 默认关闭；仅在 macOS daemon 启动环境设置 QWEN_SERVE_LIVE_NATIVE_HOST=1 时恢复 /live/host、相应能力及下载入口。已安装原生 app 不会因此自动获准连接默认 daemon。