clash-web/docs/api.md

管理 API v1

所有接口与 Web UI 同源。除首次设置、登录和登录状态外，均需要 cw_session HttpOnly cookie。修改接口还需 X-CSRF-Token，令牌由登录/首次设置/密码更新及 /auth/status 返回。会话有效期 24 小时，退出或修改密码会撤销对应会话。

统一错误：{"error":"中文说明"}；认证失败 401、CSRF/跨站失败 403、输入或应用失败 400、内核未连接的实时查询 503。

方法	/api/v1 下的路径	用途
GET	/auth/status	initialized、authenticated、csrf
POST	/auth/setup	{token,password} 首次设置；密码 12–72 字节
POST	/auth/login	{password} 登录
POST	/auth/logout	退出
PUT	/auth/password	{currentPassword,password}，撤销旧会话
GET	/status	内核状态、版本、实际出口、设置和配置错误
GET/POST	/subscriptions	列表/新增 {name,url,enabled,intervalHours}
PUT/DELETE	/subscriptions/{id}	编辑/删除
POST	/subscriptions/{id}/refresh	下载、解析、校验、应用；失败保留旧快照
GET	/nodes	脱敏节点信息，不返回密码、服务器地址等凭据
POST	/nodes/select	{mode:"manual",id} 或 {mode:"auto"}
POST	/nodes/test	{ids:[...]}，1–500 个、并发上限 8
GET	/rules	默认顺序及自定义规则
POST	/rules	{type,value,action,enabled}
PUT/DELETE	/rules/{id}	编辑/删除
GET/PUT	/settings	读取/完整替换设置；网卡与地址在当前机器校验
GET	/connections	Mihomo 活跃连接
DELETE	/connections/{id}	关闭指定连接
DELETE	/connections	关闭全部连接
POST	/system/service	{action:"start"|"stop"|"restart"}，仅固定内核 unit
GET	/system/network	网卡、IPv4 转发、TUN、资源和辅助程序检查
GET	/system/updates	手动检查 Mihomo 最新稳定版；返回当前/最新版本、更新状态（无法比较时为 null）、检查时间及发布说明 URL；成功结果缓存 10 分钟，失败返回 502
GET	/system/connectivity	9 个固定 HTTPS 测试网站的 id/name/url/category
POST	/system/connectivity/test	{siteId}；当前 VM Mihomo 分流测试；返回 status/detail/httpStatus/durationMS/tlsVerified/checkedAt；全服务并发上限 3，多余返回 429
GET	/system/backup	{version:1,exportedAt,state}，敏感配置导出
POST	/system/restore	同版本备份，校验与回滚；不覆盖管理员
GET	/events	SSE metrics，每 2 秒更新累计量、速率与连接数
GET	/logs	SSE log、heartbeat、disconnected

SSE 认证失效时发送 expired 并关闭，浏览器应重新登录。代理关闭使用 settings 的 proxyEnabled=false，进入直连模式；与停止内核进程不同，DNS/网关仍运行。

Settings 字段：proxyEnabled,tunEnabled,selectionMode,selectedNode,lanIP,lanCIDR,gateway,interface,mixedPort,dnsPort,testURL,testTimeoutMS。HTTP/SOCKS 端口为 1024–65535，DNS 为 1–65535，避免与 8080/9090 冲突。开启 TUN 要求填写内网参数并使用 DNS 端口 53。

订阅 ID/规则 ID 为稳定随机 24 位十六进制标识；节点 ID 使用 订阅ID/提供者/原节点名，对路径参数需 URL 编码。规则 type 为 DOMAIN、DOMAIN-SUFFIX、IP-CIDR，action 为 DIRECT 或 PROXY。内网规则优先，其次自定义列表，再大陆规则，最后代理。

默认手动模式首次未选节点或所选节点移除时，代理策略选择 REJECT；不会静默选择其他节点或直连。内核停止时，校验通过的配置可暂存以供下次启动；控制接口认证或通信失败不会当成停止状态忽略。