Web 服务模式

桌面端和浏览器用的是同一份 React 界面，区别只在传输层：桌面窗口通过 Tauri IPC 调用 Rust 核心，浏览器则通过 HTTP 与 WebSocket 调用同一批命令。前端启动时检测运行环境自动选择传输方式，因此两边的功能、布局、交互完全一致，你不需要学第二套界面。

Web 服务模式适合这些场景：在手机上临时切换账号；在同一局域网的另一台电脑上查看用量；把配置界面留在一台常开的机器上，其他设备只用浏览器访问。

从桌面端开启

打开桌面端的设置。
选择 Web 服务 面板。
在共享服务端口里从下拉框选择 127.0.0.1（仅本机）或 0.0.0.0（所有网卡），并填写端口。默认端口是 19527。
确认访问令牌。首次生成配置时会自动填入一个随机 UUID，可以直接用，也可以替换成自己的字符串。
点击保存，再按需要点击启动服务端口。

启动成功后，用浏览器访问 http://127.0.0.1:19527（或你设置的地址）即可。首次打开需要输入访问令牌，令牌保存在浏览器 localStorage 的 ai-switch.webToken 键下，之后同一浏览器不必重复输入。

算力池路由不再在设置页单独开关，而是在算力池顶部启停。路由已启用但共享端口未运行时，算力池顶部显示启动按钮。设置页仍可启用安全网络，通过 Tailscale 把服务暴露给自己的设备或公网；配套的访问模式可选「仅私网」或「公网访问」。这部分详见远程访问与 HTTPS。

浏览器端的三个入口

方法与路径	用途	鉴权
`POST /api/:command`	所有业务命令的统一入口，命令名放在路径里，参数放在 JSON body	需要令牌
`GET /ws/events`	WebSocket 事件流，推送账号状态、用量、终端输出等实时事件	需要令牌
`GET /health`	健康检查，用于反向代理或监控探活	不需要令牌

令牌有两种携带方式：HTTP 请求用 Authorization: Bearer <token> 请求头；WebSocket 因为无法自定义请求头，额外支持 ?token=<token> 查询参数（同时也接受 Bearer 头）。服务端比较令牌时使用常量时间比较，避免时序侧信道。

API 响应统一带上 Cache-Control: no-store，请求体上限为 12 MiB（技能包安装等操作需要较大 body）。CORS 允许任意来源发起 GET/POST/OPTIONS，因此可以从其他前端页面调用，但没有令牌依然拿不到数据。

一个手动调用的例子：

bash

curl -X POST http://127.0.0.1:19527/api/list_accounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

powershell

curl.exe -X POST http://127.0.0.1:19527/api/list_accounts `
  -H "Authorization: Bearer YOUR_TOKEN" `
  -H "Content-Type: application/json" `
  -d '{}'

配置文件

Web 服务的配置持久化在 ~/.ai-switch/web-service.json。界面上的每一项都对应其中一个字段，另外有三个字段目前只能改文件（界面上没有对应控件）：

字段	默认值	说明
`host`	`127.0.0.1`	桌面设置提供 `127.0.0.1` 与 `0.0.0.0` 两个选项；后者向所有网卡开放
`port`	`19527`	监听端口
`token`	首次生成时自动写入随机 UUID	访问令牌
`routeAccessEnabled`	`false`	是否接受算力池模型路由，由算力池顶部控制。旧配置里的 `autoStart: true` 会迁移为 `true`
`tailscaleEnabled`	`false`	是否启用 Tailscale 暴露
`tailscaleExposureMode`	`private`	`private`（仅私网）或 `public`（Funnel 公网）
`tlsEnabled`	`false`	是否启用 TLS。界面无此开关，只能改文件
`tlsCertPath`	空	证书链 PEM 路径。界面无此输入框
`tlsKeyPath`	空	私钥 PEM 路径。界面无此输入框

修改文件后需要重启 Web 服务才会生效。tlsCertPath 与 tlsKeyPath 必须同时提供，只给一个会以 web.tls_paths_incomplete 报错拒绝启动。

绑定地址与明文 HTTP

默认监听 127.0.0.1，只有本机能连接。桌面设置可改为 0.0.0.0，让局域网内其他设备直接通过 HTTP 访问；桌面版不会再因为未启用 TLS 而拒绝启动。

选择 0.0.0.0 后，终端、凭据导出、代理密钥、MCP 与技能安装等全部 Web 命令都可通过明文 HTTP 调用，访问令牌是唯一保护。请使用足够随机的令牌，只在可信局域网中开放，并自行配置防火墙；跨不可信网络时仍建议使用 Tailscale 或 TLS。

这项放宽只适用于桌面版。独立 server 仍默认拒绝非环回明文 HTTP，只有配置 TLS 或显式设置 AI_SWITCH_ALLOW_INSECURE_HTTP=1 才能启动。

浏览器里不可用的命令

有两类命令在浏览器里拿不到：

桌面独占命令（3 个）依赖原生桌面能力，浏览器调用会返回「仅桌面可用」：打开证书目录、把会话拉到系统终端应用、通过系统保存对话框导出凭据。

敏感命令包括凭据的导出/预览导入/导入、读取代理密钥、从市场安装 MCP、增删改本地 MCP 服务器、以及技能的保存/删除/安装包。桌面版直接监听 127.0.0.1 或 0.0.0.0 时，只要服务已启动并通过访问令牌鉴权，这些命令就可用；0.0.0.0 明文模式不会额外降级权限。

当桌面端保持环回监听并通过 Tailscale 暴露时，运行时闸门仍根据外部链路状态切换：

Tailscale 未启用时，环回 HTTP 可用；
Tailscale 公网模式完成 HTTPS 暴露后可用；
Tailscale 尚未建立可用外部链路时暂时关闭，返回 404「Web command is not available」。

另外要注意：桌面 Web 服务会拒绝使用空令牌或过短令牌启动，令牌实际上是必填项。

终端相关命令（创建会话、写入输入、调整大小、结束会话、列出会话）在 Web API 上是可用的，这意味着拿到令牌的人可以在你的机器上开一个 shell。请把令牌按 SSH 私钥的等级来保护。

安全注意事项

开启前请确认

访问令牌必须设置且足够随机。 所有 /api/* 与 /ws/events 请求都需要令牌，服务会拒绝空令牌或过短令牌启动。
不要随手绑 0.0.0.0。 默认的 127.0.0.1 只对本机开放；0.0.0.0 会把全部 Web 命令直接开放给局域网，未启用 TLS 时令牌是唯一保护。
令牌等价于 shell 权限。 Web API 开放了终端会话命令，泄露令牌意味着对方可以在这台机器上执行命令，同时读取所有账号配置。
令牌保存在浏览器 localStorage。 在共享或公共设备上访问后请退出并清理站点数据。
令牌轮换要手动做。 改完令牌需要重启服务，并且所有浏览器都要重新输入新令牌。
公网暴露前请三思。 需要外网访问时优先用 Tailscale 私网，只在确有必要时才启用 Funnel，且两种情况下 AI Switch 自身的令牌校验都不会被跳过。

下一步

服务器上没有桌面环境？用独立服务器直接跑 ai-switch-server。
需要从外网访问或给本地代理配 HTTPS？见远程访问与 HTTPS。
想知道桌面端与 Web 服务共享哪些数据？见桌面端。
想了解命令层在两种传输下如何复用？见架构总览。

Web 服务模式 ​

从桌面端开启 ​

浏览器端的三个入口 ​

配置文件 ​

绑定地址与明文 HTTP ​

浏览器里不可用的命令 ​

安全注意事项 ​

下一步 ​