ChatClash 文档
用 Python CLI 管理当前机器上的独立 Mihomo 引擎。安装 CLI、保存配置、生成 YAML 和重载服务是不同操作；没有远程编排或自动重启的隐含步骤。
按问题查找
| 问题 | 入口 |
|---|---|
| pip 安装成功，但环境仍冲突 | 依赖检查 |
| ChatEnv 找不到 ChatClash | 同一解释器安装 |
| 切换配置后仍读到旧值 | 字段优先级 |
自定义根目录与 --local-only |
目录边界 |
| 升级 CLI 后代理为何没变 | CLI 与服务 |
| 订阅更新后如何生效 | 校验与重载 |
| shell 导出为何不能直接使用 | 安全代理环境变量 |
安全默认值须知
- 新安装的 HTTP/SOCKS 只监听 loopback；改为 LAN/非 loopback 会在未配置认证时被拒绝。新生成配置将无 secret 的 controller 绑定到
127.0.0.1:9090。代理认证不保护管理端口；旧:9090配置升级后要刷新生成配置，并限制可信网络/防火墙入口。 - 订阅地址、认证、生成配置与备份都可能包含秘密。默认脱敏输出仅供查看，不要打印未脱敏导出或完整转换 URL。
sub update不自动重载；引擎升级不自动重启；Python 包升级不替换引擎。- 当前引擎安装和服务生命周期面向 Linux，不承诺 macOS/Windows 引擎支持。
CLI 树
chatclash --tree 带参数签名，chatclash --tree-brief 保留相同节点但省略签名。完整视图见 CLI 树，简版原样如下：
chatclash
├── --help # Show this message and exit.
├── --version # Show the version and exit.
├── --tree # Print the registered CLI tree and exit.
├── --tree-brief # Print the registered CLI tree without parameter signatures and exit.
├── --interactive # Auto prompt on missing args, -i forces interactive, -I disables it.
├── init # Initialize this machine and collect required ChatEnv config.
├── mihomo # Install and manage the local runtime.
│ ├── install # Install the local Mihomo binary.
│ ├── logs # Show local Mihomo runtime logs.
│ ├── reload # Hot-reload the current active config through Mihomo's controller.
│ ├── restart # Restart the local Mihomo runtime.
│ ├── start # Start the local Mihomo runtime.
│ ├── status # Show local Mihomo runtime status.
│ ├── stop # Stop the local Mihomo runtime.
│ ├── uninstall # Uninstall the local Mihomo binary.
│ └── update # Update the local Mihomo binary.
├── proxy # Show and update local proxy endpoint settings.
│ ├── env # Print shell proxy environment exports.
│ ├── set # Update local proxy listener settings and re-render active config.
│ ├── show # Show proxy endpoints for this machine.
│ ├── system # Manage the Windows current-user system proxy with backup and restore.
│ │ ├── disable # Restore the Windows current-user proxy settings saved at enable time.
│ │ ├── enable # Enable Windows proxy for the ready local loopback HTTP listener.
│ │ └── show # Show Windows current-user proxy status without changing it.
│ └── validate # Validate the current active Mihomo config.
├── status # Show this machine's ChatClash status.
└── sub # Manage subscription-backed runtime config.
├── converter # Install and manage the local subscription converter service.
│ ├── install # Install the local subscription converter binary.
│ ├── logs # Show local subscription converter logs.
│ ├── start # Start the local subscription converter service.
│ ├── status # Show the local subscription converter service status.
│ └── stop # Stop the local subscription converter service.
├── generate # Generate a Clash-compatible config through subscription conversion.
├── set # Store subscription operator config through ChatEnv.
├── status # Show redacted subscription config state.
├── update # Refresh the runtime config from the configured subscription.
└── url # Build a subconverter URL for the configured subscription.