命令行工具使用手册

ClashMac 27 原生附带了轻量级终端控制工具 clashmac 及其超短别名 cm。它专为极客、大模型 AI 代理（AI Agents）、以及 macOS 自动化工作流（如 Alfred、Raycast 脚本与快捷指令）设计。

1. 核心设计哲学

自动化工作流友好 JSON 结构化输出： clashmac / cm 命令行的所有标准数据输出均默认采用结构化的 JSON 格式。这极大地方便了脚本解析与程序调用，无需繁琐的正则截取。
免除繁琐配置开箱即用：命令行工具具备智能状态同步特性，能自动检测并对齐主程序当前的运行端口和鉴权口令。无需手动指定端口（-p）或口令（-s）。
多维核心控制出站与应用双向管理：支持直接控制出站节点、分流模式、测速与活跃连接；同时支持对主程序发起配置热重载、冷重启与指纹环境自动化调度。

2. 命令行安装指南

在 偏好设置 -> 高级设置 中，点击 安装 CLI 工具。系统会验证管理员权限，并在系统 /usr/local/bin 路径下同时建立 clashmac 与 cm 软链接。若已安装过旧版，也可直接在终端运行以下指令完成自动升级软链接：

bash

cm install
# 或: clashmac install

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

bash

cm version
# 返回: {"version":"v1.19.27"}

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 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
```
cm app-upgrade
```

3.6 指纹浏览器与 CDP 自动化控制 (`cm fp`)

ClashMac CLI 深度集成了对内置指纹浏览器的生命周期管理以及基于 Chrome DevTools Protocol (CDP) 的无头/远程自动化调试控制：

fp list [--json]：查询所有已创建的指纹环境状态、出口 IP、CDP 调试端口及 PID。
bash
```
cm fp list
# 表格输出包含: ID, 名称, 状态, IP, CDP 端口, PID
cm fp list --json
```
fp launch <id>：启动指定编号的指纹环境，系统会自动建立独立沙盒并智能对齐出口网络特征。
bash
```
cm fp launch 1001
# 返回: {"status":"ok","id":"1001","cdpPort":"9201"}
```
fp stop <id>：终止正在运行的指纹浏览器进程。
bash
```
cm fp stop 1001
# 返回: {"status":"stopped","id":"1001"}
```
fp delete <id>：删除指定环境并释放存储空间（系统默认环境 1001 受保护禁止删除）。
bash
```
cm fp delete 1002
```
fp goto <id> <url>：通过 CDP 协议令指定环境的当前页面即刻跳转至目标网址（若环境未运行，将自动静默拉起）。
bash
```
cm fp goto 1001 https://ip.sb
```
fp shot <id> [path] [--full]：通过 CDP 捕获网页截图。支持 --full 全网页长截图，缺省路径时自动以时间戳保存至 macOS 桌面。
bash
```
cm fp shot 1001 --full
# 标准错误输出: 网页截图成功保存至桌面: /Users/username/Desktop/CM_Shot_1001_2026-09-20_105000.png
```
fp eval <id> "<javascript>"：在指定浏览器环境的活动页面上下文中执行 JavaScript 表达式并获取执行结果。
bash
```
cm fp eval 1001 "document.title"
# 返回: {"status":"executed","id":"1001","result":"IP.SB - The simplest IP address service"}
```
fp cookie <id>：导出指定环境当前页面作用域下的全部 Cookie 列表。
bash
```
cm fp cookie 1001
```

4. 极客应用场景示例

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

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

bash

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

场景二：AI Agent / 定时任务无头自动化巡检与状态存证

借助 cm fp 系列指令，AI Agent 或本地 Shell 脚本可脱离人工干预，实现多账号矩阵的网络状态自动巡检与截图存档：

bash

#!/bin/bash
PROFILE_ID="1001"
TARGET_URL="https://ipinfo.io"

echo "1. 调度拉起指纹环境 $PROFILE_ID 并导航到目标站..."
cm fp goto "$PROFILE_ID" "$TARGET_URL" > /dev/null

echo "2. 等待页面加载并提取页面显示的 IP 地址..."
sleep 2
DETECTED_IP=$(cm fp eval "$PROFILE_ID" "document.querySelector('.ip-address')?.innerText || '未知'")

echo "3. 捕获全网页长截图存证..."
cm fp shot "$PROFILE_ID" --full

echo "4. 巡检完成，当前环境探测 IP 为: $DETECTED_IP"

命令行工具使用手册 ​

1. 核心设计哲学 ​

2. 命令行安装指南 ​

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

3.1 状态与版本查询 ​

3.2 路由分流与节点选择 ​

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

3.4 活跃连接与拦截 ​

3.5 诊断、监控与升级 ​

3.6 指纹浏览器与 CDP 自动化控制 (cm fp) ​

4. 极客应用场景示例 ​

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

场景二：AI Agent / 定时任务无头自动化巡检与状态存证 ​

命令行工具使用手册

1. 核心设计哲学

2. 命令行安装指南

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

3.1 状态与版本查询

3.2 路由分流与节点选择

3.3 配置文件管理与热重载

3.4 活跃连接与拦截

3.5 诊断、监控与升级

3.6 指纹浏览器与 CDP 自动化控制 (`cm fp`)

4. 极客应用场景示例

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

场景二：AI Agent / 定时任务无头自动化巡检与状态存证