本地配置 HTTP API

可信的本机工具可以复用 App 的配置解析、编译、已安装 GeoData 和 libXray 校验，不需要另外安装 CLI。接口不导入或保存资产，不修改设置，不下载依赖，也不启动或停止 VPN。

启用与鉴权

进入高级 → Xray → 本地 API，启用并保存。默认关闭，仅桌面端提供。App 必须运行且完成服务准备；隐藏窗口不影响使用，退出 App 则接口停止，即使系统 VPN 仍在运行。

默认地址为 http://127.0.0.1:18587，端口可设置为 1024–65535。仅监听 IPv4 回环地址，不向局域网开放。Xray 的 SOCKS／metrics 自动端口会避开已保存的 API 端口，即使 API 尚未启用；不会改写用户手动配置的入站端口。

从 App 复制 Token，交给可信本机工具的受保护凭据存储。每次请求都需要 Authorization: Bearer <token>。Token 重启后保留；重置后旧值立即失效。关闭 API 保留 Token，清空 App 数据会删除它，连接配置备份不包含它。

不要把 Token 放入 AI 提示词、URL、命令行参数、代码仓库或日志。凭据应独立配置，不与让 AI 生成的配置文本混合。工具应直连界面显示的回环地址，绕过环境代理并关闭重定向。接口不支持浏览器 Origin 请求和跨域访问。Token 无法防御已经控制同一用户账户的恶意程序。

API 版本 1

POST 使用 Content-Type: application/json，请求体上限 16 MiB。配置应作为原始文本字符串提交，不要先解析再编码，否则诊断位置不再对应原文。

{
  "kind": "raw",
  "text": "{\n  \"name\": \"Direct example\",\n  \"outbounds\": [{\"protocol\": \"freedom\", \"tag\": \"direct\"}]\n}"
}

这个示例没有代理凭据，使用直连，不是提供给用户的 VPN 节点。

可选 name 遵守对应输入类型的命名规则，不要混淆配置名称和 outbound tag。validate 不接受 options 和额外 outbounds；路由校验使用占位出站，不验证实际选中的节点组合。

编译预览

调用 compile 时，在 kind、text 之外明确提供 options 对象：

{
  "platform": "macos",
  "sessionDirectory": "/explicit/preview-directory",
  "metricsPort": 19001,
  "socksPort": 19002,
  "ipv6": true
}

• platform 支持 ios、macos、android、windows、linux，表示生成目标，不是远程运行请求。
• Windows 还需要 windowsMode: "exe" 或 "msix"；Windows/Linux 必须提供 interfaceName。
• routing 和 advanced-routing 还需要根级 outbounds 数组，真实节点数与空接入槽一致。outbound 和 raw 使用自身节点，不接受额外数组。
• 可选 tunDnsIpv4Address、tunDnsIpv6Address、logEnabled、logFilesSupported、logLevel、dnsLog、maskAddress 省略时使用编译器默认值，不继承当前连接设置。
• GeoData 路径来自当前 App 的已安装目录。生成跨平台配置不代表目标设备具有这些路径；编译不检查端口空闲或网卡存在，不创建会话目录，不写正式运行配置。

正确理解结果

同时检查 status（passed、failed、notRun）和 stage（input、compile、kernel）。HTTP 200 不等于校验通过；compile 阶段的 passed 只代表预览生成成功。

诊断包含分类码和原因；仅在可靠时附带 path、offset、line、column。偏移从 0 开始，行列从 1 开始，偏移和列按 UTF-16 code unit 计数。路径为数组，例如 ["routing", "rules", 0, "domain"]。不要从无定位的内核错误或生成的 JSON 猜测原文位置。

validationConfig 和 compiledConfig 是 JSON 文本，可能包含凭据；保存结果时应保护敏感内容。确认成功前阅读 limitations。忙碌返回 409、请求过大返回 413、服务不可用返回 503；它们都不是配置已通过。

校验构造并关闭 Core 实例，但不启动 VPN；可能产生进程级副作用，不是运行不可信配置的安全沙箱。它不下载缺失 GeoData，不检查数据库名称或数量限制，不证明实际节点组合正确，也不保证启动和联网成功。客户端超时不能取消已经进入原生层的校验，不要自动重试。

使用 AI 编写配置 · 配置边界