API 服务 — sing-box

api 服务是一个 gRPC 服务器，用于观察和控制正在运行的 sing-box 实例：服务状态、日志、出站组（选择与 URL 测试）、Clash 模式、连接跟踪，以及网络质量测试、STUN 测试或 Tailscale 操作等工具。它暴露的接口与图形客户端在本地使用的相同，因此图形客户端的远程控制功能、sing-box Dashboard 网页客户端和 sing-box api 命令都能操控远端实例。该监听器也接受 gRPC-Web（包括 improbable-eng gRPC-Web 客户端用于流式调用的 WebSocket 传输），浏览器可以直接与之通信。

选项

services[] 下的 type: "api"：

字段	类型	默认值	允许值	描述
secret	string	(empty)	<string>	共享密钥。客户端以 gRPC 元数据头 authorization: Bearer <secret> 发送它。为空时完全禁用鉴权，因此只要监听地址能被其他主机访问，就务必设置。
access_control_allow_origin	badoption.Listable[string]	*	<origin> | …	浏览器（gRPC-Web）客户端（如 sing-box Dashboard）的 CORS 允许来源。为空即 *。
access_control_allow_private_network	bool	false	true | false	应答私有网络访问（Private Network Access）预检（Access-Control-Allow-Private-Network），使公网来源的页面（例如托管版 Dashboard）可以调用监听在私有地址或回环地址上的 API。
dashboard	*APIDashboardOptions	(disabled)	true | false | <directory path> | APIDashboardOptions	在同一监听器的 /dashboard/ 下提供 sing-box Dashboard；其他浏览器请求会被重定向到那里。true 等同于 { "enabled": true }，字符串则是 { "enabled": true, "path": "<string>" } 的简写。

源码： option/api.go:11-18 · 锚定版本 v1.14.2 (af6e64c)

该服务还嵌入了 ListenOptions（listen、listen_port 等 —— 见入站）和入站 tls 块（见 TLS）。没有默认端口，请显式设置 listen_port。

dashboard

字段	类型	默认值	允许值	描述
enabled	bool	false	true | false	启用仪表盘。
path	string	dashboard	<directory path>	存放仪表盘文件的目录，相对于工作目录。空目录会通过下载填充，并用 .etag 文件跟踪；非空且没有 .etag 的目录按原样提供，永不自动更新。
download_url	string	(gh-pages archive)	<URL>	下载仪表盘所用的 zip 压缩包地址。默认为 GitHub 上 sing-box-dashboard 仓库 gh-pages 分支的压缩包。
http_client	*HTTPClientOptions	(default client)	<http_clients tag> | HTTPClientOptions	下载所用的 HTTP 客户端：内联对象，或 http_clients 条目的 tag。目录中是用户自备文件时不会使用。
update_interval	badoption.Duration	1d	<duration>	检查下载地址是否有更新版仪表盘压缩包的间隔。

源码： option/api.go:20-26 · 锚定版本 v1.14.2 (af6e64c)

sing-box api 命令

sing-box api 是该服务的命令行客户端，提供图形客户端具备的操作 —— 状态、日志、出站组、Clash 模式、连接、网络质量与 STUN 测试、Tailscale、OpenVPN / OpenConnect 认证、USB/IP 等。用 --url（或 $BOX_API_URL；未写协议时默认 http://）和 --secret（或 $BOX_API_SECRET）指向该服务。

最简示例

{
  "services": [
    {
      "type": "api",
      "tag": "api",
      "listen": "127.0.0.1",
      "listen_port": 9091,
      "secret": "change-me",
      "dashboard": true
    }
  ]
}

sing-box api --url 127.0.0.1:9091 --secret change-me status

设置 dashboard: true 后，在浏览器中打开 http://127.0.0.1:9091/ 会重定向到 Dashboard。

说明

• secret 为空意味着任何能访问该端口的人都能读取日志、切换出站组、关闭连接。请让监听器保持在回环地址上，或在对外暴露前设置 secret（以及 tls）。
• 不启用 tls 时，监听器支持 HTTP/1.1 和明文 HTTP/2（h2c）；启用 tls 时会自动把 h2 和 http/1.1 加入 ALPN 列表。
• 仪表盘在服务启动时下载，之后每隔 update_interval 重新检查。已有文件但没有 .etag 的目录被视为用户自备：按原样提供，永不覆盖。
• 该服务不需要任何构建标签。
• Clash 兼容的 REST API 是另一项独立功能，即 experimental.clash_api；见实验性功能。

跨内核说明

• Xray-core 提供 gRPC API（api.services，如 HandlerService、StatsService），需通过专用入站加路由规则访问。它不附带仪表盘。
• mihomo 使用 Clash 兼容的 REST 外部控制器，可选配网页 UI —— 与 sing-box 的 experimental.clash_api 属于同一类 API，而非本 gRPC 服务。

源码： option/api.go:11-26 · v1.14.2 (af6e64c)