Clash Tools Guide¶

clash_tools is a comprehensive toolkit that provides multiple command-line utilities for managing Clash proxy configurations and services. This guide covers all the main tools included in the package.

Tools:

Installation¶

Install using pip:

pip install clash_tools

Or install from source:

git clone <repository-url>
cd clash_tools
pip install -e .

Configuration¶

Clash Configuration File¶

All tools use a config.yaml file to configure the Clash proxy server. Default configuration:

port: 7890
socks-port: 7891
redir-port: 7892
allow-lan: true
mode: rule
log-level: info
external-controller: '0.0.0.0:9090'
secret: ''

proxies:
  -
    name: 'proxy_name'
    type: ss
    server: your-proxy-server
    port: your-proxy-port
    cipher: your-cipher
    password: your-password
    udp: true

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - 'proxy_name'

rules:
  - MATCH,PROXY

Workflow Examples¶

Complete Setup Workflow¶

Here’s a complete workflow for setting up Clash with all tools:

# 1. Start Clash service
clash_serve

# 2. In a new terminal, set up environment variables
eval "$(clash_proxy)"

# 3. Test that proxy is working
curl -I http://google.com

# 4. Configure Docker proxy
sudo clash_docker enable

# 5. Verify Docker proxy status
clash_docker status

# 6. Test Docker with proxy
docker pull hello-world

Development Workflow¶

For development environments:

# Terminal 1: Start Clash service
clash_serve

# Terminal 2: Set up development environment
eval "$(clash_proxy)"

# Now all commands in this terminal will use the proxy
npm install
pip install -r requirements.txt
git clone https://github.com/example/repo.git

Docker-Only Workflow¶

If you only need Docker proxy support:

# Ensure Clash is running (in background or another terminal)
clash_serve &

# Enable Docker proxy
sudo clash_docker enable

# Use Docker normally
docker pull nginx
docker run -d nginx

# When done, disable proxy
sudo clash_docker disable

Best Practices¶

Start Clash First: Always start the Clash service before using other tools
Use Absolute Paths: When running scripts from different directories, use absolute paths
Check Service Status: Verify Clash is running before configuring proxies
Terminal Sessions: Remember that clash_proxy only affects the current terminal session
Backup Configs: Keep backups of your config.yaml file
Test Connectivity: Always test proxy connectivity after configuration

Advanced Usage¶

Custom Configuration Directory¶

You can modify clash_serve to use a custom configuration directory by editing the script.

Automated Scripts¶

Create shell scripts to automate common workflows:

#!/bin/bash
# start-clash-env.sh

# Start Clash in background
clash_serve &
CLASH_PID=$!

# Wait for service to start
sleep 2

# Set environment variables
eval "$(clash_proxy)"

# Configure Docker
sudo clash_docker enable

echo "Clash environment ready!"
echo "Use 'kill $CLASH_PID' to stop Clash service"

Environment-Specific Configurations¶

You can maintain different config files for different environments:

# Development
cp config.dev.yaml config.yaml
clash_serve

# Production
cp config.prod.yaml config.yaml
clash_serve

Integration with Other Tools¶

The tools can be integrated with other development tools:

# In your .bashrc or .zshrc
alias start-proxy="clash_serve & sleep 2 && eval \"$(clash_proxy)\""
alias stop-proxy="pkill clash && unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY all_proxy ALL_PROXY"

Troubleshooting¶

General Issues¶

Issue: Config File Not Found

If any tool reports config file not found:

Ensure config.yaml exists in the same directory as the scripts
Check file permissions (should be readable)
Verify the YAML syntax is correct

Debug Information¶

Check Clash service status:

ps aux | grep clash

Check if ports are listening:

netstat -tuln | grep 7890
netstat -tuln | grep 7891

View environment variables:

env | grep -i proxy