命令行工具使用手册

ClashMac 27.0 原生附带了一个功能强大的轻量级终端控制工具 clashmac。它专为极客、大模型 AI 代理、以及 macOS 的自动化工作流（如 Alfred、Raycast 脚本和快捷指令）设计。

1. 核心设计哲学

自动化工作流友好 JSON 结构化输出： clashmac 命令行的所有标准数据输出均默认采用结构化的 JSON 格式。这极大地方便了 Alfred Workflow、Raycast 脚本以及 macOS 快捷指令直接读取和解析字段，无需进行任何繁琐的文本行截取或正则表达式过滤。
免除繁琐配置开箱即用：命令行工具具备智能状态同步特性，能自动检测并对齐主程序当前的运行端口和鉴权口令。您无需在命令中手动指定端口（-p）或口令密码（-s）。若需要在多终端或多应用环境中进行独立控制，也支持通过环境变量临时覆盖连接参数。
多维核心控制出站与应用双向管理：命令行支持直接控制代理的出站节点、流量监控和延迟测试；同时，即使主程序在后台静默运行，您也可以通过命令行向主程序发起载入新订阅配置、强行切断连接或一键执行全局测速等应用级指令。

2. 命令行安装指南

在 系统设置 -> 高级设置 中，点击 安装 CLI 工具。系统会弹出管理员密码框进行权限验证，并在系统的 /usr/local/bin 路径下建立名为 clashmac 的快捷软链接。

安装成功后，在终端运行以下指令测试：

bash

clashmac version

3. 子命令速查表与返回结构

3.1 状态与版本查询

status：获取当前运行状态与路由模式。

bash

clashmac status
# 返回: {"mode":"rule","status":"running","version":"v1.19.27"}

app-status：获取主程序的聚合状态（包括当前正在活跃的配置文件名称）。
bash
```
clashmac app-status
```
version：获取当前的版本号。
bash
```
clashmac version
```
configs：输出当前工作内存中的完整配置参数。
bash
```
clashmac configs
```

3.2 路由分流与节点选择

mode：查询或切换出站模式（可选：rule / global / direct）。

bash

clashmac mode            # 查询模式
clashmac mode direct     # 切换至直连模式

proxies：列出当前所有的策略组及每个组下属的代理节点（包含延迟）。
bash
```
clashmac proxies
```

select <group> <proxy>：为指定策略组切换出站节点。

bash

clashmac select "Proxy" "HK_01"
# 返回: {"action":"selected","group":"Proxy","proxy":"HK_01"}

delay <proxy> [url]：实时测试指定代理节点的延迟。可指定测速的 HTTP 地址，默认使用系统配置的测速地址。
bash
```
clashmac delay "HK_01"
# 返回: {"delay":45,"proxy":"HK_01"}
```

3.3 配置文件管理与热重载

profile list：列出当前所有已加载的配置文件。

bash

clashmac profile list
# 返回: [{"active":true,"fileName":"config.yaml","name":"Default Profile"}]

profile switch <name>：一键切换当前处于激活状态的配置文件。
bash
```
clashmac profile switch "HongKong.yaml"
```
reload：无感热重载当前配置。引擎进程不退出，在内存中动态热更新当前的配置文件（保留活跃的长连接，避免因重载导致全面断网）。
bash
```
clashmac reload
# 返回: {"action":"reload","status":"ok"}
```
restart：强行冷重启代理服务。该操作会销毁并重新创建底层的网络守护进程，重置所有内存缓存，会导致当前所有的活跃网络连接瞬时中断。
bash
```
clashmac restart
```

3.4 活跃连接与拦截

connections：列出当前内存中所有的活跃 TCP/UDP 网络连接。
bash
```
clashmac connections
```
close <id>：强行掐断指定 ID 的网络连接（ID 可从 connections 指令中提取）。
bash
```
clashmac close "8f1a23bc-90de"
```
close-all：一键切断当前系统所有的活动套接字，强迫客户端重新匹配分流规则。
bash
```
clashmac close-all
```

3.5 诊断、监控与升级

traffic：在终端开启一个流式监听。程序不会退出，每秒以 JSON 格式输出实时上传与下载的网速快照。按 Ctrl+C 退出。
bash
```
clashmac traffic
# Stderr 输出:  Watching traffic (Ctrl+C to stop)...
# Stdout 输出: {"download":10452,"upload":482}
```
logs [level]：流式输出实时运行日志（默认输出 info，可选 debug / warning / error）。按 Ctrl+C 退出。
bash
```
clashmac logs debug
```
validate [path]：在本地脱机状态下预先验证指定配置文件的语法完整性，防止因格式错误导致服务无法启动。
bash
```
clashmac validate "/path/to/profile.yaml"
```
providers：输出当前所有的外部节点和规则订阅源详情。
bash
```
clashmac providers
```
health-check：强制执行一次全局测速与最优节点选择。
bash
```
clashmac health-check
```
check-update & upgrade [channel]：检测并更新代理引擎核心（channel 支持 stable / alpha / smart）。
bash
```
clashmac upgrade smart
```
app-check-update & app-upgrade：触发主程序的检测与静默重启升级。
bash
```
clashmac app-upgrade
```

4. 极客应用场景示例

Alfred / Raycast 脚本一键测速并切换到最快节点

您可以直接在 Alfred Workflow 或 Raycast 脚本中绑定 shell 指令，在状态栏之外更快速地控制网络状态：

bash

#!/bin/bash
# 自动筛选 Proxy 策略组下延迟低于 50ms 且最快的节点并完成切换
fastest_node=$(clashmac proxies | jq -r '.[] | select(.name=="Proxy") | .proxies | sort_by(.delay) | .[0].name')
clashmac select "Proxy" "$fastest_node"
echo "已为您自动切换到最快节点: $fastest_node"

命令行工具使用手册 ​

1. 核心设计哲学 ​

2. 命令行安装指南 ​

3. 子命令速查表与返回结构 ​

3.1 状态与版本查询 ​

3.2 路由分流与节点选择 ​

3.3 配置文件管理与热重载 ​

3.4 活跃连接与拦截 ​

3.5 诊断、监控与升级 ​

4. 极客应用场景示例 ​

Alfred / Raycast 脚本一键测速并切换到最快节点 ​

命令行工具使用手册

1. 核心设计哲学

2. 命令行安装指南

3. 子命令速查表与返回结构

3.1 状态与版本查询

3.2 路由分流与节点选择

3.3 配置文件管理与热重载

3.4 活跃连接与拦截

3.5 诊断、监控与升级

4. 极客应用场景示例

Alfred / Raycast 脚本一键测速并切换到最快节点