Claude Code Usage Guide: From Official Configuration to Integrating Third-Party Models

Claude Code will automatically read the project context, understand the code structure, and execute the operations.

III. Slash Commands

This section summarizes the built-in commands and key points of custom commands in Claude Code.

• Built-in commands are used for session control, status viewing, exporting, debugging, etc. They are frequently used, so it is recommended to memorize the common ones.
• Custom commands are defined via Markdown files, supporting parameters, bash execution, file references, and permission controls. They are suitable for solidifying common templates into commands.

Built-in Commands (Common)

• /add-dir: Add an additional working directory.
• /agents: Manage custom sub-agents (AI subagents).
• /bashes: List/manage background bash tasks.
• /bug: Report a bug (sends the conversation to Anthropic).
• /clear: Clear conversation history.
• /compact [instructions]: Compress conversation context, optionally with focusing instructions.
• /config: Open the settings interface (Config tab).
• /context: Visualize current context usage in a color grid.
• /cost: Display token usage statistics.
• /doctor: Check the health status of the Claude Code installation.
• /exit: Exit the REPL.
• /export [filename]: Export the current session to a file or clipboard.
• /help: Get the list of help topics and usage instructions.
• /hooks: Manage hook configurations related to tool events.
• /ide: Manage IDE integration and display status.
• /init: Initialize the project with the CLAUDE.md guide.
• /install-github-app: Set up Claude GitHub Actions for a repository.
• /login, /logout: Switch or log out of the Anthropic account.
• /mcp: Manage MCP server connections and OAuth authorization.
• /memory: Edit the memory file (CLAUDE.md).
• /model: Select or switch the AI model.
• /output-style [style]: Set the output style.
• /permissions: View or update permission rules.
• /plugin: Manage Claude Code plugins.
• /pr-comments: View PR comments.
• /privacy-settings: View/update privacy settings.
• /release-notes: View release notes.
• /resume: Resume the session.
• /review: Request a code review.
• /rewind: Roll back the session or code state.
• /sandbox: Enable a restricted sandboxed bash (isolated file system and network).
• /security-review: Perform a security review of pending changes on the current branch.
• /status: Open the status interface (shows version, model, account, and connectivity).
• /statusline: Set the status line UI.
• /terminal-setup: Install Shift+Enter shortcut for iTerm2 / VSCode.
• /todos: List current todo items.
• /usage: Display subscription plan usage limits and rate limit status.
• /vim: Enter vim mode (alternating insert/command modes).

Custom Commands (Key Points)

Syntax: /<command-name> [arguments]

Command Types:

• Project commands (project): Located in .claude/commands/, shared among the team.
• User commands (user): Located in ~/.claude/commands/, available across all projects.
• Plugin commands: Distributed with plugins, located in the plugin's commands/ directory, named using the namespace /plugin-name:command.
• MCP commands: Dynamically discovered by connected MCP servers, formatted as /mcp__<server>__<prompt> [args].

Parameter Support:

• $ARGUMENTS: Captures the entire argument string (suitable for free text).
• $1, $2, ...: Access individual arguments by position (suitable for structured arguments and default value handling).

Bash Execution: Bash commands can be executed in command files using the ! prefix (requires enabling the corresponding allowed-tools in the frontmatter).

File References: Use @path/to/file to reference file content within the command context.

Frontmatter Metadata: Supports fields including allowed-tools, argument-hint, description, model, disable-model-invocation, etc.

SlashCommand Tool Behavior and Permissions

• The SlashCommand tool only supports user-defined custom commands (does not include built-in commands).
• Character Budget: Default 15,000 characters (adjustable via the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable).
• Disabling Method: Prohibit the SlashCommand tool via permission rules, or add disable-model-invocation: true in the command's frontmatter.
• Permission Rules: Supports exact matching (SlashCommand:/commit) and prefix matching (SlashCommand:/review-pr:*).

Engineering Best Practices

• Turn repetitive review, testing, and release templates into custom commands to reduce manual operations.
• For commands that perform writes or commits, strictly set allowed-tools and review command files during the PR process.
• Prioritize project commands for sharing best practices within a team; personal commands are for individual efficiency improvements.
• Use review steps or multi-model validation for critical outputs to avoid unreliable results from low-cost models.

Skills vs Slash commands

• Slash commands: Suitable for simple, repetitive prompts that are explicitly triggered manually.
• Skills: Suitable for complex, multi-file capabilities with automated discovery, including scripting and validation flows.

For more details, refer to the "Custom slash commands," "Plugin commands," and "MCP slash commands" sections in the official documentation.

IV. Why Are Third-Party Models Needed?

Using official models directly presents the following issues:

• High Cost: Billed by token, significant long-term usage expenses.
• Quota Restrictions: Daily/weekly call limits, with frequently adjusted policies.
• Poor Flexibility: Inability to use third-party models like DeepSeek, OpenRouter, or local LLMs.

Solution: Insert a routing/proxy layer into the invocation chain to achieve:

• Routing to different models based on task type or cost strategy.
• Reducing overall usage costs.
• Improving service availability.
• Gaining greater flexibility in model selection.

V. Quick Integration: Direct Connection with Compatible Models

5.1 DeepSeek Integration

DeepSeek offers an interface compatible with the Claude API. "Painless replacement" can be achieved via environment variables:

Bash/Zsh Configuration (Add to ~/.bashrc or ~/.zshrc):

bash
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=${YOUR_DEEPSEEK_API_KEY}
export API_TIMEOUT_MS=600000
export ANTHROPIC_MODEL=deepseek-chat
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

Fish Configuration (Add to ~/.config/fish/config.fish):

fish
set -gx ANTHROPIC_BASE_URL https://api.deepseek.com/anthropic
set -gx ANTHROPIC_AUTH_TOKEN <YOUR_DEEPSEEK_API_KEY>
set -gx API_TIMEOUT_MS 600000
set -gx ANTHROPIC_MODEL deepseek-chat
set -gx ANTHROPIC_SMALL_FAST_MODEL deepseek-chat
set -gx CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 1

After configuration, running claude will automatically direct all model calls to DeepSeek.

5.2 Zhipu GLM Integration

Automatic Configuration (Recommended)

bash
curl -fsSL "https://cdn.bigmodel.cn/install/claude_code_env.sh" | bash

The script automatically modifies ~/.claude/settings.json:

json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your_zhipu_api_key",
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
    "API_TIMEOUT_MS": "3000000"
  }
}

Manual Configuration

Edit ~/.claude/settings.json:

json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your_zhipu_api_key",
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic", // Mainland China region
    // "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",  // International version
    "API_TIMEOUT_MS": "3000000",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.6"
  }
}

Environment Variable Method (Use if JSON method fails):

bash
export ANTHROPIC_AUTH_TOKEN=your_zhipu_api_key
export ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic  # Mainland China region
# export ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic  # International version
export API_TIMEOUT_MS=3000000
export ANTHROPIC_DEFAULT_HAIKU_MODEL=glm-4.5-air
export ANTHROPIC_DEFAULT_SONNET_MODEL=glm-4.6
export ANTHROPIC_DEFAULT_OPUS_MODEL=glm-4.6

5.3 Precautions

• Ensure the third-party API is compatible with the current Claude Code version.
• Choose the appropriate model based on the task characteristics (e.g., deepseek-reasoner for complex reasoning).
• Pay attention to API documentation updates and adjust configurations as necessary.

VI. Advanced Solutions: Intelligent Routing and Switching Tools

When more complex model management strategies are needed, direct connection methods may be insufficient. Here we introduce two open-source tools:

• Claude Code Router (CCR): A command-line routing proxy supporting dynamic routing and multi-model collaboration.
• CC-Switch: A cross-platform desktop application providing visual configuration management.

6.1 Claude Code Router (CCR)

CCR is a command-line routing solution offering:

• Unified management of multiple Providers.
• A flexible routing rules engine.
• Request/response transformers.
• Interactive model switching.
• A complete logging and statistics system.

Installation

bash
npm install -g @musistudio/claude-code-router

Configuration

Create ~/.claude-code-router/config.json:

json
{
  "APIKEY": "your-secret-key",
  "PROXY_URL": "http://127.0.0.1:7890",
  "LOG": true,
  "API_TIMEOUT_MS": 600000,
  "NON_INTERACTIVE_MODE": false,

  "Providers": [
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "sk-xxx",
      "models": [
        "google/gemini-2.5-pro-preview",
        "anthropic/claude-sonnet-4",
        "anthropic/claude-3.5-sonnet",
        "anthropic/claude-3.7-sonnet:thinking"
      ],
      "transformer": {
        "use": ["openrouter"]
      }
    },
    {
      "name": "deepseek",
      "api_base_url": "https://api.deepseek.com/chat/completions",
      "api_key": "sk-xxx",
      "models": ["deepseek-chat", "deepseek-reasoner"],
      "transformer": {
        "use": ["deepseek"],
        "deepseek-chat": {
          "use": ["tooluse"]
        }
      }
    },
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen2.5-coder:latest"]
    },
    {
      "name": "gemini",
      "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
      "api_key": "sk-xxx",
      "models": ["gemini-2.5-flash", "gemini-2.5-pro"],
      "transformer": {
        "use": ["gemini"]
      }
    },
    {
      "name": "volcengine",
      "api_base_url": "https://ark.cn-beijing.volces.com/api/v3/chat/completions",
      "api_key": "sk-xxx",
      "models": ["deepseek-v3-250324", "deepseek-r1-250528"],
      "transformer": {
        "use": ["deepseek"]
      }
    },
    {
      "name": "modelscope",
      "api_base_url": "https://api-inference.modelscope.cn/v1/chat/completions",
      "api_key": "",
      "models": [
        "Qwen/Qwen3-Coder-480B-A35B-Instruct",
        "Qwen/Qwen3-235B-A22B-Thinking-2507"
      ],
      "transformer": {
        "use": [["maxtoken", { "max_tokens": 65536 }], "enhancetool"],
        "Qwen/Qwen3-235B-A22B-Thinking-2507": {
          "use": ["reasoning"]
        }
      }
    },
    {
      "name": "dashscope",
      "api_base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
      "api_key": "",
      "models": ["qwen3-coder-plus"],
      "transformer": {
        "use": [["maxtoken", { "max_tokens": 65536 }], "enhancetool"]
      }
    },
    {
      "name": "aihubmix",
      "api_base_url": "https://aihubmix.com/v1/chat/completions",
      "api_key": "sk-",
      "models": ["Z/glm-4.5", "claude-opus-4-20250514", "gemini-2.5-pro"]
    }
  ],

  "Router": {
    "default": "deepseek,deepseek-chat",
    "background": "ollama,qwen2.5-coder:latest",
    "think": "deepseek,deepseek-reasoner",
    "longContext": "openrouter,google/gemini-2.5-pro-preview",
    "longContextThreshold": 60000,
    "webSearch": "gemini,gemini-2.5-flash"
  }
}

Configuration Explanation:

Base Configuration:

• PROXY_URL: Proxy server address.
• LOG: Enable logging (true/false).
• LOG_LEVEL: Log level (fatal/error/warn/info/debug/trace).
• APIKEY: Access key (optional; if enabled, the client must provide it in the Authorization or x-api-key header).
• HOST: Service listening address (default 127.0.0.1).
• NON_INTERACTIVE_MODE: Non-interactive mode, suitable for CI/Docker environments.
• API_TIMEOUT_MS: Upstream model call timeout (milliseconds).

Logging System (Dual Log Architecture):

1. Server Logs: HTTP requests, API calls, written to ~/.claude-code-router/logs/ccr-*.log.
2. Application Logs: Routing decisions, business events, written to ~/.claude-code-router/claude-code-router.log.

Providers Configuration:

• name: Provider identifier.
• api_base_url: API base URL.
• api_key: Authentication key (supports environment variable interpolation, e.g., $OPENAI_API_KEY or ${OPENAI_API_KEY}).
• models: List of supported models.
• transformer: Request/response transformation rules to adapt to different API protocols.

Router Configuration:

• default: Default model route.
• background: Model for background tasks (usually local or low-cost models).
• think: Model for complex reasoning tasks.
• longContext: Model for long-context tasks.
• longContextThreshold: Long context threshold (in tokens).
• webSearch: Model for tasks requiring web search.

Running

bash
# Start Claude Code
ccr code

# Restart the service
ccr restart

# Open the UI management interface
ccr ui

# CLI model management
ccr model

CLI Model Management (ccr model):

• View current configuration.
• Switch models.
• Add new models.
• Create new Providers (including API endpoints, keys, model lists, Transformer configurations).

Use Cases

Cost Optimization:

• Short prompts or standard generation → Local models or cheap APIs.
• Complex reasoning or critical output → High-quality paid models.

Service Reliability:

• Main model unavailable → Automatically degrade to a backup model.
• Critical tasks → Parallel calls to multiple models with voting decisions.

Flexible Expansion:

• Seamless integration of new Providers and models.
• Custom transformers to adapt to special API protocols.

Advantages and Caveats

Advantages:

• ✅ High flexibility, supports any model with a compatible API.
• ✅ Significant reduction in usage costs.
• ✅ Powerful expansion capabilities and policy configuration.
• ✅ Supports environment variable interpolation for secure API Key management.

Caveats:

• ⚠️ Latency Increase: The proxy layer introduces network overhead.
• ⚠️ Compatibility: Requires transformers to adapt to different API protocols.
• ⚠️ Security: Avoid storing API Keys in plain text in configuration files; use environment variables.
• ⚠️ Quality Differences: Low-cost models may produce hallucinations or errors, requiring validation and fallback mechanisms.

6.2 CC-Switch

CC-Switch is a cross-platform desktop application that provides visual configuration management for Claude Code / Codex / Gemini CLIs.

Core Features

Provider Management:

• One-click switching between Claude Code, Codex, and Gemini API configurations.
• Speed testing: Measures API endpoint latency and visualizes quality metrics.
• Import/Export: Backup and restore configurations, automatic rotation (keeping the last 10).
• Provider duplication and drag-and-drop sorting.
• Multi-endpoint management and custom configuration directories (supports cloud sync).

MCP Management:

• Unified management of MCP servers for all three applications in a single panel.
• Supports SSE (Server-Sent Events) transport type.
• Intelligent JSON parsing + automatic correction for Codex TOML format.
• Unified import/export + bidirectional synchronization.
• Built-in templates (mcp-fetch, mcp-filesystem, etc.).

Skills Management:

• Automatic scanning of skills in GitHub repositories (3 curated repositories pre-configured).
• One-click install/uninstall to ~/.claude/skills/.
• Custom repository support + subdirectory scanning.
• Full lifecycle management (discovery/installation/update).

Prompts Management:

• Management of multiple preset system prompts (unlimited presets, quick switching).
• Cross-application support (CLAUDE.md for Claude / AGENTS.md for Codex / GEMINI.md for Gemini).
• Markdown editor (CodeMirror 6 + real-time preview).
• Intelligent fallback protection, preserving manual edits.

Other Features:

• Deep Link protocol (ccswitch://): One-click import of provider configurations.
• Environment variable conflict detection: Automatically detects cross-application configuration conflicts.
• System tray quick switching.
• Single instance guardian process.
• Built-in automatic updater.
• Atomic write + rollback protection.
• Multi-language support (Chinese/English/Japanese).
• Startup on boot (one-click enable/disable).

Installation

System Requirements:

• Windows: Windows 10 or later.
• macOS: macOS 10.15 (Catalina) or later.
• Linux: Mainstream distributions like Ubuntu 22.04+ / Debian 11+ / Fedora 34+.

Windows: Download the CC-Switch-v{version}-Windows.msi installer or the CC-Switch-v{version}-Windows-Portable.zip portable version from the Releases page.

macOS:

Method 1: Homebrew Installation (Recommended)

bash
brew tap farion1231/ccswitch
brew install --cask cc-switch

Update:

bash
brew upgrade --cask cc-switch

Method 2: Manual Download Download CC-Switch-v{version}-macOS.zip from the Releases page.

Note: Since the author does not have an Apple Developer account, you might see an "unidentified developer" warning on first launch. Close the warning, then go to "System Settings" → "Privacy & Security" → click "Open Anyway," and it will work normally afterward.

ArchLinux:

bash
paru -S cc-switch-bin

Linux: Download CC-Switch-v{version}-Linux.deb or CC-Switch-v{version}-Linux.AppImage from the Releases page.

Quick Start

Basic Usage:

1. Add Provider: Click "Add Provider" → Select a preset or create a custom configuration.
2. Switch Provider:
   • Main Interface: Select provider → Click "Enable".
   • System Tray: Directly click the provider name (takes effect immediately).
3. Apply Changes: Restart the terminal or the Claude Code / Codex / Gemini client.
4. Revert to Official: Select the "Official Login" preset (Claude/Codex) or "Google Official" preset (Gemini), restart the client, and follow the login/OAuth process.

MCP Management:

• Location: Click the "MCP" button in the top right corner.
• Add Server: Use built-in templates or custom configurations.
• Enable/Disable: Use the switch to control which servers sync to the real-time configuration.
• Import/Export: Import existing MCP servers from Claude/Codex/Gemini configuration files.

Skills Management:

• Location: Click the "Skills" button in the top right corner.
• Discover Skills: Automatically scan pre-configured GitHub repositories.
• Install Skills: Click "Install" to install to ~/.claude/skills/ with one click.
• Uninstall Skills: Click "Uninstall" to safely remove and clean up status.
• Manage Repositories: Add/remove custom GitHub repositories.

Prompts Management:

• Location: Click the "Prompts" button in the top right corner.
• Create Preset: Create unlimited system prompt presets using the Markdown editor.
• Switch Preset: Select preset → Click "Activate" to apply immediately.
• Sync Mechanism:
  • Claude: ~/.claude/CLAUDE.md
  • Codex: ~/.codex/AGENTS.md
  • Gemini: ~/.gemini/GEMINI.md
• Protection Mechanism: Automatically save the current prompt content before switching, preserving manual edits.

Technical Architecture

Data Storage:

• SQLite + JSON dual-layer architecture.
• Synchronizable data (providers, MCP, Prompts, Skills) stored in SQLite.
• Device-specific data (window state, local paths) stored in JSON.

Tech Stack:

• Frontend: React + TypeScript + Tailwind CSS
• Backend: Rust (Tauri)
• Database: SQLite
• Editor: CodeMirror 6

6.3 CCR vs CC-Switch Comparison

Selection Advice:

• CCR: Suitable for scenarios requiring advanced routing policies, automated deployment, and CI/CD integration.
• CC-Switch: Suitable for local development and scenarios requiring visual management and frequent configuration switching.
• Combination: Use CC-Switch to manage basic configurations, and CCR to handle complex routing logic.

VII. System Architecture

┌──────────────────────┐
│  Claude Code CLI     │
└──────────┬───────────┘
           │
           ▼
┌────────────────────────────────────────┐
│  Router / Proxy (CCR / CC-Switch)      │
│  • Routing Rules Engine                │
│  • Request Transformation              │
│  • Response Aggregation                │
│  • Logging and Billing                 │
└────┬──────────┬──────────┬──────────────┘
     │          │          │
     ▼          ▼          ▼
┌─────────┐ ┌────────┐ ┌─────────────┐
│DeepSeek │ │Local   │ │Official     │
│(Reasoning)│ │LLM     │ │Claude       │
│         │ │(Low Cost)│ │(Fallback)   │
└─────────┘ └────────┘ └─────────────┘
     │          │          │
     └──────────┴──────────┘
                │
                ▼
     ┌────────────────────┐
     │  Merge / Filter / Log│
     └────────────────────┘
                │
                ▼
     ┌────────────────────┐
     │  Return to Frontend│
     └────────────────────┘

VIII. References

• Claude Code Official Documentation
• DeepSeek Anthropic API Documentation
• Zhipu GLM Documentation (International)
• Zhipu GLM Documentation (China)
• Claude Code Router (CCR) Open Source Project
• CC-Switch Open Source Project