ClaudeCode 使用指北

1. 基础

Claude Code，简称 CC，是 Anthropic 发布的智能编码工具，在终端中运行。

默认情况下，Claude Code 与 Anthropic 官方账号紧密相连，由 Anthropic 的官方服务器提供底层模型支持并消耗 Token。

同时，如果使用国内网络直连，存在被封号的风险。

因此，需要一个工具，让 Claude Code 可以摆脱 Anthropic 账号运行。

Claude Code Router，简称 CCR，是一个开源工具。主要功能：拦截 Claude Code 发出的 API 请求，然后路由到任意 AI 模型服务（如 OpenRouter、DeepSeek、Gemini 或本地 Ollama 等），实现"Claude Code 客户端 + 自定义后端模型"的灵活组合。

---

2. 安装 Claude Code

# 安装最新版本
npm i -g @anthropic-ai/claude-code

# 安装最新版本
npm i -g @anthropic-ai/claude-code@latest

# 安装指定版本
npm install -g @anthropic-ai/claude-code@2.1.162

---

3. 配置 Claude Code

编辑配置文件：~/.claude/settings.json

原则：环境变量的优先级高于一切本地配置文件

{
    // ...略

    "hasCompletedOnboarding": true,                             // 跳过登录验证
    "alwaysThinkingEnabled": false,                             // 按需，对于不支持思考模式的LLM（如本地部署的轻量模型），可以关闭思考模式。

    // ...略

    // 配置凭证
    "env": {
        "NO_PROXY": "localhost,127.0.0.1",
        "ANTHROPIC_AUTH_TOKEN": "${MY_API_KEY}",                // 访问 BaseUrl 的 TOKEN
        "ANTHROPIC_BASE_URL": "${MY_BASE_URL}",                 // 【关键】BaseUrl, 不需要携带 `/v1/chat/completions`
        "ANTHROPIC_MODEL": "${MY_MODEL_NAME}",
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "${MY_MODEL_NAME}",    // 可选
        "ANTHROPIC_DEFAULT_SONNET_MODEL": "${MY_MODEL_NAME}",   // 可选
        "ANTHROPIC_DEFAULT_OPUS_MODEL": "${MY_MODEL_NAME}",     // 可选
        "CLAUDE_CODE_SUBAGENT_MODEL": "${MY_MODEL_NAME}"        // 可选
    }
    // ...略
}

---

4. Claude Code 常用命令

# 查看版本
claude -v

# 升级
claude update

# 启动
claude

4.1 启动后，输入 / 可以查看 claude 支持的命令

# 退出 claude
/exit

# 清空当前对话历史，快速开启一个干净的新任务
/clear

# 生成摘要，压缩长对话
/compact

---

5. Claude Code Router

5.1 安装

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

5.2 配置

方式一：修改配置文件

路径：~/.claude-code-router/config.json

配置文件参考样例：查看 GitHub 项目源码中 config.example.json 文件

{
    // ... 略

    "Providers": [                                                          // 模型 Providers
        {
            "name": "kimi",                                                 // 设置 Provider 名称
            "api_base_url": "xxxxxxxxxxxx/v1/chat/completions",             // 【关键】需要携带 `v1/chat/completions`
            "api_key": "sk-xxxxx",
            "models": [
                "kimi-k2-0711-preview"                                      // 模型列表，可在 cc 中进行模型切换
            ]
        }
    ],
    "Router": {
        "default": "${provider_name},${model_name}",                        // 关联，如，"default": "kimi,kimi-k2-0711-preview"
        "background": "${provider_name},${model_name}",
        "think": "${provider_name},${model_name}",
        "longContext": "${provider_name},${model_name}",
        "webSearch": "${provider_name},${model_name}"
    }

    // ... 略
}

方式二：通过 UI 界面进行配置

# 若报 403 错误，则将 127.0.0.1 改为 localhost
# 如：http://localhost:3456/ui/
ccr ui

5.3 启动

首次启动时，需要配置。一路点击确定即可，之后就可以对话。

# 启动路由服务，默认本地代理地址为：http://127.0.0.1:3456
ccr start

# 更改配置后需要重启
ccr restart

---

6. Claude Code Router 与 Claude Code 配合

6.1 方式一：通过 Claude Code Router 直接启动 Claude Code

# 启动
ccr code

工作原理：

• 自动注入环境变量 ANTHROPIC_BASE_URL 指向 CCR 的本地代理端口
• 自动注入环境变量 ANTHROPIC_API_KEY 绕过官方鉴权
• 然后拉起 ClaudeCode 客户端

6.2 方式二

1. 先启动 Claude Code Router

ccr start

2. 再修改 Claude Code 的配置文件，指向 Claude Code Router

{
    // ...略

    // 跳过登录验证
    "hasCompletedOnboarding": true

    // ...略

    // 配置凭证
    "env": {
        "NO_PROXY": "localhost,127.0.0.1",
        "ANTHROPIC_API_KEY": "sk-disabled",                         // 访问 BaseUrl 的 TOKEN
        "ANTHROPIC_BASE_URL": "http://127.0.0.1:3456",              // 【关键】BaseUrl, 不需要携带 `/v1/chat/completions`
    }
    // ...略
}

3. 最后再启动 Claude Code

claude

注意：Claude Code 启动后，UI 上面显示的"模型名称"并不是 Claude Code Router 指定的模型名称，这是正常现象。

---

扩展：Claude Code Router 软件架构

• 第一层： Client Applications（如：Claude Code CLI、Custom API Clients 等）
• 第二层： Claude Code Router 核心组件，包含三部分 HTTP Server、Request Router、Transformer
• 第三层： LLM Providers（如 OpenRouter、DeepSeek、Ollama、Gemini、OpenAI-compatible APIs 等大模型）

其中：

组件	说明
HTTP Server	负责监听、接收和响应 Application（如 Claude Code 或客户端的 API 调用）的 HTTP 请求，将请求交由 Router 组件处理。充当整个服务的入口点，并管理请求的生命周期，包括解析请求体、返回响应等。
Request Router	根据请求内容和配置，决定每一个 HTTP 请求应该被分配给哪个 LLM 模型服务商。
Transformer	定义请求/响应转换器，根据 LLM 模型服务商的 API 规范，将请求/响应中的数据进行格式/参数等的适配与转换（如参数增强、字段转换、容错处理等）。