Use this skill to initialize the project when it is missing, run the normal operator SOP when it is present, and shorten troubleshooting when something breaks.
Start Here
- Rebuild local state before making changes:
whoami
echo "$SHELL"
uname -m
readlink /proc/1/exe
command -v clashctl || true
- Locate the actual install root before editing files. Default is
~/clashctl, but the real path comes from the installed.env. - Decide which path applies:
- no installation detected: initialize first
- installation detected: follow the SOP sections below
- failure or drift detected: troubleshoot before making bigger changes
- Read references/project-map.md when you need exact file paths, bundled fallback details, or failure-mode notes.
Initialization Workflow
Always prefer the latest upstream repository first. Only fall back to the bundled copy under scripts/upstream-project/ when GitHub access is slow, blocked, or unavailable.
Prepare a working tree with:
rm -rf /tmp/clash-for-linux-install
git clone --depth 1 https://github.com/nelvko/clash-for-linux-install.git /tmp/clash-for-linux-install || {
mkdir -p /tmp/clash-for-linux-install
cp -R scripts/upstream-project/. /tmp/clash-for-linux-install/
}
cd /tmp/clash-for-linux-install
Then:
- Review
.envand change only the values that matter for this host. - Prefer
mihomounless the user explicitly needs legacyclash. - Set
CLASH_CONFIG_URLin.envor pass the subscription URL directly toinstall.sh. - Run
bash install.sh. - Verify with
clashctl status,clashui, andclashsecret.
If the fallback copy was used, call out that it is a trimmed vendored upstream copy and may lag behind the current GitHub head.
Installed-State Workflow
When an installation already exists:
- Read the installed
.envfirst. - Inspect these files in order:
resources/config.yamlresources/mixin.yamlresources/runtime.yamlresources/profiles.yaml
- Treat
runtime.yamlas generated output. Do not hand-edit it unless the user explicitly wants a temporary experiment. - Prefer the built-in wrappers over raw edits whenever a wrapper already exists.
Operator SOP
Daily control
clashon: start the kernel and enable shell proxy variablesclashoff: stop the kernel and clear shell proxy variablesclashstatus: inspect statusclashlog: inspect logsclashproxy on|off: toggle only shell proxy variables
Subscription management
clashsub add '<url>'clashsub lsclashsub use <id>clashsub update [id]clashsub update --convert [id]only when validation or parser compatibility requires itclashsub log
Quote any subscription URL that contains &, ?, or other shell-sensitive characters.
Config management
Understand the merge model before editing anything:
config.yamlis the active raw subscriptionmixin.yamlcontains the highest-priority local overridesruntime.yamlis the merged runtime file actually passed to the kernel
Use:
clashmixin -eto edit mixin safelyclashmixin -cto inspect the base subscriptionclashmixin -rto inspect the effective runtime config
Web UI and secrets
clashuiprints the effective local and public Web UI endpointsclashsecretshows the current secretclashsecret <new_secret>rotates the secret and restarts the service
Tun mode
clashtunclashtun onclashtun off
Require elevated privileges before changing Tun mode. Turn Tun off before uninstalling.
Upgrade and uninstall
clashupgradeclashupgrade -vclashupgrade --releaseclashupgrade --alphabash uninstall.sh
Troubleshooting Workflow
Use this sequence:
- Confirm the install root, kernel choice, and init mode from
.env. - Confirm required files exist under
bin/andresources/. - Confirm whether the kernel process is running.
- Read
resources/runtime.yamlinstead of guessing ports or Web UI endpoints. - Inspect the newest available log:
/var/log/<kernel>.logfor many root installsresources/<kernel>.logfornohupor non-root installs
- For subscription problems, inspect:
resources/temp.yamlresources/temp.yaml.rawbin/subconverter/latest.logresources/profiles.log
- For port conflicts, let the project auto-randomize and then re-check
runtime.yamlorclashui. - For Tun failures, search the logs for:
Start TUN listening errorunsupported kernel versionTun adapter listening at
TUN listening iface
Operating Rules
- Always try the latest GitHub repository before using the bundled snapshot.
- Work from the prepared repo root when running
install.shoruninstall.sh. - Do not manually delete the install directory when
uninstall.shcan revoke shell hooks, service definitions, and cron entries cleanly. - Prefer wrappers over raw edits:
clashsubfor subscriptionsclashmixinfor custom rulesclashsecretfor the Web UI tokenclashtunfor Tun
- Edit
.envonly for installation-wide defaults such as kernel choice, install path, GitHub proxy, or subscription user agent.
Bundled Resources
scripts/upstream-project/Trimmed vendored copy of the upstream project with the install scripts, command wrappers, init scripts, and required resources preserved. Use it as the fallback source forcp -R scripts/upstream-project/. /tmp/clash-for-linux-install/when GitHub clone fails.
Read references/project-map.md whenever you need the exact file layout, bundled fallback details, command cheat sheet, or failure-mode map.