cc-switch/docs/user-manual/en/5-faq/5.4-env-conflict.md

5.4 Environment Variable Conflicts

Overview

CC Switch automatically detects conflicts between system environment variables and app configurations, preventing configurations from being unexpectedly overridden.

Detected environment variables:

• ANTHROPIC_API_KEY - Claude API key
• ANTHROPIC_BASE_URL - Claude API endpoint
• OPENAI_API_KEY - OpenAI API key
• GEMINI_API_KEY - Gemini API key
• Other related environment variables

Conflict Warning

When a conflict is detected, a yellow warning banner appears at the top of the interface:

Warning: Environment variable conflict detected
Found X environment variables that may conflict with CC Switch configuration
[Expand] [Dismiss]

View Conflict Details

Click the "Expand" button to view detailed information:

Field	Description
Variable Name	Environment variable name
Variable Value	Currently set value
Source	Where the variable originates from

Source Types

Source	Description
User Registry	Windows user-level environment variable
System Registry	Windows system-level environment variable
Shell Configuration	macOS/Linux shell configuration file
System Environment	System-level environment variable

Resolve Conflicts

Select Variables to Remove

1. Check the environment variables you want to remove
2. Or click "Select All" to select all conflicting variables

Remove Variables

1. Click the "Remove Selected" button
2. Confirm the removal operation
3. CC Switch will automatically back up and remove the selected variables

Automatic Backup

A backup is automatically created before removal:

• Backup location: ~/.cc-switch/env-backups/
• Backup format: JSON file
• Includes variable name, value, source, and other information

Dismiss Warning

If you confirm the conflict does not affect usage, you can:

1. Click the "Dismiss" button on the right side of the warning banner
2. The warning will be temporarily hidden
3. Detection will run again on next launch

Manual Resolution

If you prefer not to use CC Switch to remove variables, you can handle them manually:

Windows

1. Open "System Properties > Advanced > Environment Variables"
2. Find the conflicting variable in User or System variables
3. Delete or modify the variable

macOS / Linux

1. Edit the shell configuration file (e.g., ~/.zshrc, ~/.bashrc)
2. Delete or comment out the relevant export statements
3. Reload the configuration: source ~/.zshrc

Why Do Conflicts Occur

Environment variables typically take priority over configuration files, which may cause:

• CC Switch provider configurations being overridden
• API requests being sent to the wrong endpoint
• Using the wrong API key

Best Practices

1. Use CC Switch to manage configurations: Avoid setting API keys in system environment variables
2. Check regularly: Pay attention to conflict warnings and address them promptly
3. Back up important variables: Confirm backups exist before removal

Restore Deleted Variables

If you accidentally deleted environment variables:

1. Find the backup file: ~/.cc-switch/env-backups/
2. Open the corresponding JSON file
3. Manually restore the variable to the system environment