# 本地配置 HTTP API

Source: https://onexray.com/zh/docs/advanced/local-api/
Description: 通过桌面 App 的本地 HTTP API 校验 OneXray JSON、生成运行配置预览，了解 Token、输入类型和诊断结果的边界。
Language: zh-CN
Last updated: 2026-09-28


可信的本机工具可以复用 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

| 方法与路径 | 结果 |
| --- | --- |
| `GET /api/v1/info` | API、App、内核版本，以及宿主平台和支持的配置类型 |
| `POST /api/v1/config/validate` | App 解析和验证投影，再调用 libXray 配置校验 |
| `POST /api/v1/config/compile` | 生成运行配置预览，不调用内核校验或执行配置 |

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

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

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

| `kind` | `text` 的含义 |
| --- | --- |
| `outbound` | 节点编辑器中的单个 outbound 对象，**不是**外包 `outbounds` 的文档 |
| `routing` | 包含空接入槽的[常规自定义路由](https://onexray.com/zh/docs/configuration/custom-routing/) |
| `advanced-routing` | 遵守独立字段边界的[高级自定义 JSON](https://onexray.com/zh/docs/configuration/advanced-routing/) |
| `raw` | [完整 Raw JSON](https://onexray.com/zh/docs/configuration/raw-json/) 配置 |

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

## 编译预览

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

```json
{
  "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 编写配置](https://onexray.com/zh/docs/ai/) · [配置边界](https://onexray.com/zh/docs/configuration/compatibility/)