Clash API 接口文档与使用技巧 – wiki大全

作者： /

Clash API 深度解析：文档与实战技巧

Clash 作为一款功能强大的网络代理工具，不仅仅拥有丰富的图形化客户端，还提供了一套完整的 RESTful API。这套 API 允许开发者和高级用户通过编程方式与 Clash 核心进行交互，实现自动化控制、状态监控和高级定制功能。本文将深入探讨 Clash API 的文档和常见使用技巧。

一、 开启 API 访问

默认情况下，出于安全考虑，Clash 的 API 接口可能并未开启或只监听本地回环地址。要使用 API，你需要在 Clash 的配置文件 (config.yaml) 中找到或添加 external-controller 部分。

一个典型的配置如下：

“`yaml

config.yaml

… 其他配置 …

RESTful API 的监听地址

external-controller: ‘127.0.0.1:9090’

（可选）为 API 设置密码，增加安全性

secret: ‘your-secret-password’

… 其他配置 …

“`

  • external-controller: 设置 API 的监听地址和端口。127.0.0.1:9090 表示只允许本机访问。如果你需要从局域网内其他设备访问，可以设置为 0.0.0.0:9090，但请务必确保你的网络环境安全。
  • secret: 设置一个密钥。如果设置了此项，所有 API 请求（GET 请求除外）都需要在 HTTP Header 中加入 Authorization: Bearer <secret> 才能成功调用，极大地增强了安全性。

修改配置后，重启 Clash 使之生效。

二、核心 API 接口文档

以下是 Clash API 中最常用的一些接口。我们将使用 curl 作为示例工具。

1. 根节点 (/)
  • 方法: GET
  • 描述: 获取 Clash 的版本信息。
  • 示例:
    bash
    curl http://127.0.0.1:9090/
  • 返回:
    json
    {"hello":"clash"}
    （部分版本会返回更详细的版本号）
2. 流量 (/traffic)
  • 方法: GET
  • 描述: 这是一个 WebSocket 接口，用于实时推送上行和下行流量信息。
  • 示例:
    bash
    # 需要使用支持 WebSocket 的客户端连接
    # 例如 wscat:
    # wscat -c ws://127.0.0.1:9090/traffic
  • 返回 (持续推送):
    json
    {"up": 1024, "down": 20480}
    (up/down 代表上/下行速度，单位：Bytes/s)
3. 日志 (/logs)
  • 方法: GET
  • 描述: 同样是 WebSocket 接口，用于实时推送 Clash 的日志信息。
  • 示例:
    bash
    # wscat -c ws://127.0.0.1:9090/logs
  • 返回 (持续推送):
    json
    {"type": "info", "payload": "Match GEOIP CN to DIRECT"}
4. 代理与策略组 (/proxies)
  • 方法: GET, PUT
  • 描述:
    • GET /proxies: 获取所有可用的代理节点和策略组的信息。
    • GET /proxies/<name>: 获取指定名称的代理或策略组的详细信息，例如延迟。
    • PUT /proxies/<name>: 切换策略组中选中的节点。
  • 示例 1: 获取所有代理
    bash
    curl http://127.0.0.1:9090/proxies
  • 示例 2: 切换策略组 PROXY 的节点为 节点A
    bash
    curl http://127.0.0.1:9090/proxies/PROXY -X PUT -H "Content-Type: application/json" -d '{"name": "节点A"}'
    (请将 PROXY 和 节点A 替换为你的策略组和节点名称)
5. 规则 (/rules)
  • 方法: GET
  • 描述: 获取当前生效的所有规则。
  • 示例:
    bash
    curl http://127.0.0.1:9090/rules
  • 返回:
    json
    {
    "rules": [
    { "type": "DOMAIN-SUFFIX", "payload": "google.com", "proxy": "PROXY" },
    { "type": "GEOIP", "payload": "CN", "proxy": "DIRECT" },
    { "type": "MATCH", "payload": "", "proxy": "PROXY" }
    ]
    }
6. 连接 (/connections)
  • 方法: GET, DELETE
  • 描述:
    • GET /connections: 获取当前所有活跃的 TCP 连接。
    • DELETE /connections/<id>: 关闭一个指定的连接。
  • 示例 1: 查看所有连接
    bash
    curl http://127.0.0.1:9090/connections
  • 示例 2: 关闭所有连接 (常用于需要立即断开所有代理连接的场景)
    bash
    curl http://127.0.0.1:9090/connections -X DELETE
7. 配置 (/configs)
  • 方法: GET, PUT, PATCH
  • 描述:
    • GET /configs: 获取当前的各项配置，如端口、模式等。
    • PATCH /configs: 修改部分配置。这是热重载的关键，可以在不重启 Clash 的情况下应用新配置。
  • 示例: 动态修改 socks5 端口为 7891
    bash
    curl http://127.0.0.1:9090/configs -X PATCH -H "Content-Type: application/json" -d '{"socks-port": 7891}'

三、实战使用技巧

技巧 1: 编写自动化脚本 (以 Python 为例)

API 的最大魅力在于自动化。例如，我们可以编写一个 Python 脚本来自动选择延迟最低的节点。

“`python
import requests
import json

— 配置 —

CLASH_API_URL = “http://127.0.0.1:9090”

如果设置了 secret, 取消下面的注释并填入你的 secret

HEADERS = {‘Authorization’: ‘Bearer your-secret-password’}

HEADERS = {}

你要操作的策略组名称

SELECTOR_NAME = “PROXY”

def get_proxies():
“””获取所有代理和策略组”””
try:
res = requests.get(f”{CLASH_API_URL}/proxies”, headers=HEADERS)
res.raise_for_status()
return res.json()[‘proxies’]
except requests.exceptions.RequestException as e:
print(f”Error getting proxies: {e}”)
return None

def switch_proxy(selector_name, proxy_name):
“””切换策略组的节点”””
try:
url = f”{CLASH_API_URL}/proxies/{selector_name}”
payload = {“name”: proxy_name}
res = requests.put(url, headers=HEADERS, json=payload)
res.raise_for_status()
print(f”Successfully switched {selector_name} to {proxy_name}”)
return True
except requests.exceptions.RequestException as e:
print(f”Error switching proxy: {e}”)
return False

def main():
“””主函数：找到延迟最低的节点并切换”””
proxies = get_proxies()
if not proxies:
return

# 筛选出指定策略组的所有可用节点
if SELECTOR_NAME not in proxies:
    print(f"Error: Selector '{SELECTOR_NAME}' not found.")
    return

available_nodes = proxies[SELECTOR_NAME]['all']

# 此处省略了延迟测试的逻辑，实际应用中你需要通过 /proxies/<name>/delay 接口
# 或者自行实现测速来找到最佳节点。为简化示例，我们直接选择列表中的第一个。
# 假设 '节点A' 是我们想要切换的目标
best_node = available_nodes[0]

print(f"Found available nodes: {available_nodes}")
print(f"Attempting to switch to the first node: {best_node}")

switch_proxy(SELECTOR_NAME, best_node)

if name == “main“:
main()
``
**注意**: 上述脚本只是一个基础框架。一个完整的脚本还需要调用/proxies//delay接口来对available_nodes列表中的每个节点进行延迟测试，然后选出delay` 最低的节点进行切换。

技巧 2: 结合系统工具
  • 状态栏显示: 你可以编写一个极简脚本，定期（如每 5 秒）调用 /traffic 和 /proxies 接口，将当前网速和所用节点显示在 macOS 的 BitBar/SwiftBar 或 Linux 的 i3status 等系统状态栏工具中。
  • 快捷键切换: 在操作系统中设置全局快捷键，绑定一个 curl 命令，实现一键切换到特定节点（如回家/办公模式）。
技巧 3: 理解 Web UI 的工作原理

像 Yacd、Clash-Dashboard 这样流行的 Web UI，其本质就是一个纯前端项目。它们的所有功能，包括显示节点、图表、切换代理、查看日志等，都是通过调用上述 Clash API 来实现的。理解了 API，你甚至可以自己定制一个符合个人习惯的控制面板。

四、总结

Clash 的 RESTful API 是一座功能宝库，它将 Clash 的能力从一个单纯的代理客户端扩展为了一个可编程的网络核心。无论是想实现复杂的自动化策略，还是想将其集成到你自己的工作流中，掌握其 API 的使用都将为你打开一扇新的大门。

希望这篇文章能帮助你更好地理解和使用 Clash API。建议收藏 Clash 官方文档 以便随时查阅最准确的信息。

滚动至顶部