---
url: /configuration/api.md
description: Clash 兼容控制 API、TLS、CORS、面板和 DoH
---

# api

打开 mihomo/Clash 兼容的 REST 控制 API。

```yaml check
api:
  listen: 127.0.0.1:9090
  secret: change-me

dns:
  servers:
    default: {type: udp, address: 127.0.0.1:53}
  final: default
```

## 字段

### listen

* 类型：`SocketAddr`。
* 必填：与 `unix` 至少写一个。
* 默认：无。
* 取值：`IP:port`。

### unix

* 类型：路径。
* 必填：与 `listen` 至少写一个。
* 默认：无。
* 取值：相对或绝对路径。

Unix socket 不要求 bearer secret。

### tls

* 类型：[TLS 服务端块](/configuration/shared/tls-server)。
* 必填：可选。
* 默认：无 TLS。
* 限制：只能使用静态 `certificate` + `key`；ACME、REALITY、Kotodama 在这里被拒绝，并要求 `listen` 存在。

### secret

* 类型：字符串。
* 必填：可选。
* 默认：无。
* 取值：任意字符串；客户端以 Bearer token 发送。

### cors

* 类型：映射。
* 必填：可选。
* 默认：允许任意 origin 和私有网络请求。

### cors.allow_origins

* 类型：字符串数组。
* 默认：`["*"]`。
* 取值：`*`、带一个 `*` 的名字，或具体 origin。

### cors.allow_private_network

* 类型：布尔值。
* 默认：`true`。

### ui

* 类型：路径。
* 必填：可选。
* 默认：无。
* 取值：面板目录；下载结果也放在这里。

### ui_name

* 类型：字符串。
* 必填：可选。
* 默认：无。
* 取值：`ui` 下的单个目录名，不能包含路径分隔、`.` 或 `..`。

### ui_url

* 类型：HTTP/HTTPS URL。
* 必填：可选。
* 默认：metacubexd 的下载地址。
* 取值：zip 或 gzip 压缩的 tar。

### ui_via

* 类型：出站名。
* 必填：可选。
* 默认：`route.final`。

### doh

* 类型：字符串路径。
* 必填：可选。
* 默认：不启用 DoH。
* 取值：以 `/` 开头；常写 `/dns-query`。该路径启用后不要求 secret。

## 说明

`listen` 和 `unix` 可同时存在。写 `api` 却没有两者会被拒绝。面板在 `/ui` 提供。

## 相关

* [TLS 服务端](/configuration/shared/tls-server)
* [运行](/getting-started/run)
* [命令行](/getting-started/cli)