mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-04-22 08:59:45 +08:00
docs: restructure user manual for i18n and add EN/JA translations
Reorganize docs/user-manual/ from flat structure to language subdirectories (zh/, en/, ja/) with shared assets/. Move existing Chinese docs into zh/, fix image paths, add multilingual navigation README, and translate all 23 markdown files (~4500 lines each) to English and Japanese.
This commit is contained in:
Jason
340
docs/user-manual/en/5-faq/5.1-config-files.md
Normal file
340
docs/user-manual/en/5-faq/5.1-config-files.md
Normal file
@@ -0,0 +1,340 @@
|
||||
# 5.1 Configuration Files
|
||||
|
||||
## CC Switch Data Storage
|
||||
|
||||
### Storage Directory
|
||||
|
||||
Default location: `~/.cc-switch/`
|
||||
|
||||
Customizable location in settings (for cloud sync).
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
~/.cc-switch/
|
||||
├── cc-switch.db # SQLite database
|
||||
├── settings.json # Device-level settings
|
||||
└── backups/ # Automatic backups
|
||||
├── backup-20251230-120000.json
|
||||
├── backup-20251229-180000.json
|
||||
└── ...
|
||||
```
|
||||
|
||||
### Database Contents
|
||||
|
||||
`cc-switch.db` is a SQLite database that stores:
|
||||
|
||||
| Table | Contents |
|
||||
|-------|----------|
|
||||
| providers | Provider configurations |
|
||||
| provider_endpoints | Provider endpoint candidate list |
|
||||
| mcp_servers | MCP server configurations |
|
||||
| prompts | Prompt presets |
|
||||
| skills | Skill installation status |
|
||||
| skill_repos | Skill repository configurations |
|
||||
| proxy_config | Proxy configuration |
|
||||
| proxy_request_logs | Proxy request logs |
|
||||
| provider_health | Provider health status |
|
||||
| model_pricing | Model pricing |
|
||||
| settings | App settings |
|
||||
|
||||
### Device Settings
|
||||
|
||||
`settings.json` stores device-level settings:
|
||||
|
||||
```json
|
||||
{
|
||||
"language": "zh",
|
||||
"theme": "system",
|
||||
"windowBehavior": "minimize",
|
||||
"autoStart": false,
|
||||
"claudeConfigDir": null,
|
||||
"codexConfigDir": null,
|
||||
"geminiConfigDir": null,
|
||||
"opencodeConfigDir": null,
|
||||
"openclawConfigDir": null
|
||||
}
|
||||
```
|
||||
|
||||
These settings are not synced across devices.
|
||||
|
||||
### Automatic Backups
|
||||
|
||||
The `backups/` directory stores automatic backups:
|
||||
|
||||
- Automatically created before each configuration import
|
||||
- Retains the most recent 10 backups
|
||||
- File names include timestamps
|
||||
|
||||
## Claude Code Configuration
|
||||
|
||||
### Configuration Directory
|
||||
|
||||
Default: `~/.claude/`
|
||||
|
||||
### Key Files
|
||||
|
||||
```
|
||||
~/.claude/
|
||||
├── settings.json # Main configuration file
|
||||
├── CLAUDE.md # System prompt
|
||||
└── skills/ # Skills directory
|
||||
└── ...
|
||||
```
|
||||
|
||||
### settings.json
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_API_KEY": "sk-xxx",
|
||||
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
|
||||
},
|
||||
"permissions": {
|
||||
"allow_file_access": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `env.ANTHROPIC_API_KEY` | API key |
|
||||
| `env.ANTHROPIC_BASE_URL` | API endpoint (optional) |
|
||||
| `env.ANTHROPIC_AUTH_TOKEN` | Alternative authentication method |
|
||||
|
||||
### MCP Configuration
|
||||
|
||||
MCP server configuration is in `~/.claude.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"mcp-fetch": {
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Codex Configuration
|
||||
|
||||
### Configuration Directory
|
||||
|
||||
Default: `~/.codex/`
|
||||
|
||||
### Key Files
|
||||
|
||||
```
|
||||
~/.codex/
|
||||
├── auth.json # Authentication configuration
|
||||
├── config.toml # Main configuration + MCP
|
||||
└── AGENTS.md # System prompt
|
||||
```
|
||||
|
||||
### auth.json
|
||||
|
||||
```json
|
||||
{
|
||||
"OPENAI_API_KEY": "sk-xxx"
|
||||
}
|
||||
```
|
||||
|
||||
### config.toml
|
||||
|
||||
```toml
|
||||
# Basic configuration
|
||||
base_url = "https://api.openai.com/v1"
|
||||
model = "gpt-4"
|
||||
|
||||
# MCP servers
|
||||
[mcp_servers.mcp-fetch]
|
||||
command = "uvx"
|
||||
args = ["mcp-server-fetch"]
|
||||
```
|
||||
|
||||
## Gemini CLI Configuration
|
||||
|
||||
### Configuration Directory
|
||||
|
||||
Default: `~/.gemini/`
|
||||
|
||||
### Key Files
|
||||
|
||||
```
|
||||
~/.gemini/
|
||||
├── .env # Environment variables (API Key)
|
||||
├── settings.json # Main configuration + MCP
|
||||
└── GEMINI.md # System prompt
|
||||
```
|
||||
|
||||
### .env
|
||||
|
||||
```bash
|
||||
GEMINI_API_KEY=xxx
|
||||
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
|
||||
GEMINI_MODEL=gemini-pro
|
||||
```
|
||||
|
||||
### settings.json
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"mcp-fetch": {
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `mcpServers` | MCP server configuration |
|
||||
|
||||
## OpenCode Configuration
|
||||
|
||||
### Configuration Directory
|
||||
|
||||
Default: `~/.opencode/`
|
||||
|
||||
### Key Files
|
||||
|
||||
```
|
||||
~/.opencode/
|
||||
├── config.json # Main configuration file
|
||||
├── AGENTS.md # System prompt
|
||||
└── skills/ # Skills directory
|
||||
└── ...
|
||||
```
|
||||
|
||||
## OpenClaw Configuration
|
||||
|
||||
### Configuration Directory
|
||||
|
||||
Default: `~/.openclaw/`
|
||||
|
||||
### Key Files
|
||||
|
||||
```
|
||||
~/.openclaw/
|
||||
├── openclaw.json # Main configuration file (JSON5 format)
|
||||
├── AGENTS.md # System prompt
|
||||
└── skills/ # Skills directory
|
||||
└── ...
|
||||
```
|
||||
|
||||
### openclaw.json
|
||||
|
||||
OpenClaw uses a JSON5 format configuration file with the following main sections:
|
||||
|
||||
```json5
|
||||
{
|
||||
// Model provider configuration
|
||||
models: {
|
||||
mode: "merge",
|
||||
providers: {
|
||||
"custom-provider": {
|
||||
baseUrl: "https://api.example.com/v1",
|
||||
apiKey: "your-api-key",
|
||||
api: "openai-completions",
|
||||
models: [{ id: "model-id", name: "Model Name" }]
|
||||
}
|
||||
}
|
||||
},
|
||||
// Environment variables
|
||||
env: {
|
||||
ANTHROPIC_API_KEY: "sk-..."
|
||||
},
|
||||
// Agent default model configuration
|
||||
agents: {
|
||||
defaults: {
|
||||
model: {
|
||||
primary: "provider/model"
|
||||
}
|
||||
}
|
||||
},
|
||||
// Tool configuration
|
||||
tools: {},
|
||||
// Workspace file configuration
|
||||
workspace: {}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `models.providers` | Provider configuration (mapped to CC Switch's "providers") |
|
||||
| `env` | Environment variable configuration |
|
||||
| `agents.defaults` | Agent default model settings |
|
||||
| `tools` | Tool configuration |
|
||||
| `workspace` | Workspace file management |
|
||||
|
||||
## Configuration Priority
|
||||
|
||||
CC Switch's priority when modifying configurations:
|
||||
|
||||
1. **CC Switch Database** - Single source of truth (SSOT)
|
||||
2. **Live Configuration Files** - Written when switching providers
|
||||
3. **Backfill Mechanism** - Reads from live files when editing the current provider
|
||||
|
||||
## Manual Configuration Editing
|
||||
|
||||
### Safe to Edit Manually
|
||||
|
||||
- CLI tool configuration files (will be backfilled by CC Switch)
|
||||
- CC Switch's `settings.json`
|
||||
|
||||
### Not Recommended to Edit Manually
|
||||
|
||||
- `cc-switch.db` database file
|
||||
- Backup files
|
||||
|
||||
### Sync After Editing
|
||||
|
||||
If you manually edit CLI tool configurations:
|
||||
|
||||
1. Open CC Switch
|
||||
2. Edit the corresponding provider
|
||||
3. You will see the manual changes have been backfilled
|
||||
4. Save to sync to the database
|
||||
|
||||
## Configuration Migration
|
||||
|
||||
### Migrating from Older Versions
|
||||
|
||||
CC Switch v3.7.0 migrated from JSON files to SQLite:
|
||||
|
||||
- Automatic migration on first launch
|
||||
- Displays a notification upon successful migration
|
||||
- Old configuration files are retained as backups
|
||||
|
||||
### Cross-device Migration
|
||||
|
||||
1. Export configuration on the source device
|
||||
2. Import configuration on the target device
|
||||
3. Or use the cloud sync feature
|
||||
|
||||
## Configuration Backup Recommendations
|
||||
|
||||
### Regular Backups
|
||||
|
||||
It is recommended to regularly export configurations:
|
||||
|
||||
1. Settings > Advanced > Data Management
|
||||
2. Click "Export"
|
||||
3. Save to a secure location
|
||||
|
||||
### Backup Contents
|
||||
|
||||
The export file includes:
|
||||
|
||||
- All provider configurations
|
||||
- MCP server configurations
|
||||
- Prompt presets
|
||||
- App settings
|
||||
|
||||
### Not Included
|
||||
|
||||
- Usage logs (large data volume)
|
||||
- Device-level settings (not suitable for cross-device)
|
||||
Reference in New Issue
Block a user