Claude Code 想接自定义 AI？这篇 ccr 教程帮你一次打通

想要的是 Claude Code 的工作流，不一定非得是 Anthropic 的那条默认链路。ccr 干的就是这件事：保留 Claude Code 的交互体验，把模型请求转到你自己的服务上。

如果你已经习惯了 Claude Code 那套在终端里读代码、改文件、跑命令、起子代理的手感，但又想接入自己的 OpenAI 兼容网关、DeepSeek、OpenRouter、Gemini，甚至本地模型，那 @musistudio/claude-code-router 基本就是绕不过去的一站。

这篇不讲虚的，直接讲三件事：

ccr 到底是什么，适合谁用
怎么安装，怎么配
ccr ui、ccr code、ccr activate 到底分别该在什么时候用

顺手再把一个很容易把人坑半天的环境变量也捎上：

export CLAUDE_CODE_ATTRIBUTION_HEADER=0

这玩意儿对接第三方服务时，真的很关键。

一、`ccr` 到底是什么

一句话：它是 Claude Code 和你自定义模型服务之间的“翻译层 + 路由层”。

Claude Code 本身会按自己的方式发请求，而 ccr 会在中间接住这些请求，然后再转发给你配置好的目标模型服务。

它最香的地方不只是“能转发”，而是它顺手把很多现实世界的脏活也做了：

模型路由：不同任务走不同模型。普通对话一个模型，Plan Mode 一个模型，长上下文再切一个模型。
多供应商兼容：DeepSeek、OpenRouter、Gemini、Ollama、Volcengine 这些都能接。
请求转换：很多厂商都说自己“兼容 OpenAI”，但兼容到什么程度，懂的都懂。ccr 的 transformer 就是专门收拾这些接口细节差异的。
不改 Claude Code 使用习惯：你还是在用 Claude Code，不是换了另一个 Agent 工具。

Aha Moment 在这里：

你想保留的，其实不是某个模型，而是 Claude Code 这套 Agent 工作流本身。

ccr 做的，就是把“模型能力”和“Claude Code 体验”拆开。前者你自己选，后者继续享受。

二、哪些人特别适合上 `ccr`

如果你符合下面任意一条，基本就值得装：

想让 Claude Code 走自己的 OpenAI 兼容网关。
想把日常编码流量切到更便宜的模型，比如 DeepSeek 或某个聚合平台。
想让不同任务走不同模型，压缩成本。
想接本地模型或私有部署服务。
想在 GitHub Actions、容器、CI 里跑 Claude Code，但不走官方直连。

如果你本来就是 Claude Max 或官方 API 的重度用户，而且没成本、网络或合规压力，那直接用官方链路通常更省心。

三、先装 Claude Code，再装 `ccr`

这里有个小细节很重要：Claude Code 官方现在更推荐原生安装方式，不再推荐用 npm 安装 Claude Code 本体。

但 ccr 自己仍然是一个 npm 包，所以最稳妥的组合通常是：

Claude Code 用官方推荐方式安装
ccr 用 npm 全局安装

1、安装 Claude Code

Linux / macOS 直接这样：

curl -fsSL https://claude.ai/install.sh | bash

装完之后确认一下：

claude --version

2、安装 `ccr`

ccr 需要 Node.js >= 18。没装 Node 的先装 Node。

然后直接：

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

确认命令可用：

ccr --help

如果这里找不到命令，十有八九是全局 npm bin 目录没进 PATH。

四、先别急着手改 JSON，优先用 `ccr ui`

如果你第一次接触 ccr，我更推荐的顺序不是先打开配置文件，而是先跑：

ccr ui

它会打开一个 Web UI，让你直接管理 config.json。

这个命令特别适合两类人：

第一次配置，怕 JSON 写错
想频繁切换模型和服务

很多人第一次上手就卡在“配置结构到底该怎么写”。这时候别硬扛，先用 ccr ui，比手敲舒服太多。

而且它有个隐藏优势：你会先建立对 Providers、Router、模型列表这些概念的直觉，再回头看 JSON，脑子会清楚很多。

所以我的建议很直接：

先用 ccr ui 跑通第一份配置
真需要精细化维护时，再回头手改配置文件

五、需要精细控制时，再手动配 `config.json`

当然，Web UI 再舒服，最终底层还是这份文件：

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

它支持直接引用环境变量，所以 API Key 不建议硬编码在文件里，直接用 $变量名 就行。

先看一份**适合“自定义 OpenAI 兼容服务”**的最小配置：

{
  "LOG": true,
  "API_TIMEOUT_MS": 600000,
  "Providers": [
    {
      "name": "myproxy",
      "api_base_url": "https://your-llm-gateway.example.com/v1/chat/completions",
      "api_key": "$MY_LLM_API_KEY",
      "models": ["coding-model", "reasoning-model", "long-context-model"]
    }
  ],
  "Router": {
    "default": "myproxy,coding-model",
    "background": "myproxy,coding-model",
    "think": "myproxy,reasoning-model",
    "longContext": "myproxy,long-context-model",
    "longContextThreshold": 60000
  }
}

然后把密钥放到 shell 环境里：

export MY_LLM_API_KEY="你的密钥"

1、这些字段分别是干嘛的

配置里最核心的其实就两块：

`Providers`

这部分定义“你能连到哪些服务”。

name：给这个服务起个名字
api_base_url：目标接口地址
api_key：密钥
models：这个服务下可选的模型列表

`Router`

这部分决定“什么场景走哪个模型”。

default：日常默认模型
background：后台小任务
think：思考型任务，比如 Plan Mode
longContext：长上下文任务
longContextThreshold：多长算长，默认可以理解成 60K 左右

这套设计很像给 Claude Code 配了一个“模型调度器”。它不需要你每次都手动切模型，但你又能保留精细控制权。

2、不同服务需要不同 `transformer`

这里是新手第二个高频坑。

很多服务虽然都长得像 OpenAI API，但细节并不一样。比如工具调用、max_tokens、cache_control、推理字段、流式输出这些地方，经常会有微妙差异。

所以你可以这样理解：

普通 OpenAI 兼容网关：通常可以先不加 transformer
DeepSeek 官方接口：常见写法是 "use": ["deepseek"]
Gemini 官方接口：常见写法是 "use": ["gemini"]
OpenRouter：常见写法是 "use": ["openrouter"]

比如 DeepSeek 官方接口常见会这样配：

{
  "name": "deepseek",
  "api_base_url": "https://api.deepseek.com/chat/completions",
  "api_key": "$DEEPSEEK_API_KEY",
  "models": ["deepseek-chat", "deepseek-reasoner"],
  "transformer": {
    "use": ["deepseek"],
    "deepseek-chat": {
      "use": ["tooluse"]
    }
  }
}

为什么还要加 tooluse？因为有些模型工具调用不积极，ccr 可以通过额外转换把这个行为往可用方向掰一下。

别小看这个细节。很多时候你以为是模型不行，实际是协议没喂对。

六、真正开始用：`ccr code`

配置完之后，最直接的启动方式就是：

ccr code

这个命令可以理解成：让 Claude Code 带着 ccr 的路由配置一起启动。

你会得到的体验是：

进入的还是 Claude Code 交互界面
但模型请求已经被转发到你配置的第三方服务了
Router 规则开始生效

如果你刚改过配置文件，记得重启一下服务：

ccr restart

这个动作别忘。很多“我明明改了怎么没生效”的锅，最后都能落到这里。

七、想继续用原来的 `claude` 命令？用 `ccr activate`

有些人不喜欢每次都敲 ccr code，更习惯直接：

claude

那就用：

eval "$(ccr activate)"

它会把需要的环境变量注入当前 shell，会话里后续再跑 claude，就会自动走 ccr。

这一步本质上做了几件事：

把 ANTHROPIC_BASE_URL 指到本地 ccr 服务
设置认证头相关变量
顺手处理 NO_PROXY、超时、遥测等细节

所以它很适合：

你已经形成了 claude 的肌肉记忆
你想让基于 Agent SDK 的应用也顺手走同一套路由

如果你想长期生效，可以把它写进 ~/.bashrc 或 ~/.zshrc：

eval "$(ccr activate)"

八、模型切换别来回改配置，直接用 `/model`

ccr 很舒服的一点，是它不逼你每次改配置文件。

在 Claude Code 里你可以直接用：

/model myproxy,reasoning-model

这个场景特别适合：

当前任务突然变难，想临时切到强一点的模型
现在只是改小 bug，不想一直烧贵模型
某个模型工具调用状态不稳定，先临时切走

如果你更喜欢终端交互式管理，也可以跑：

ccr model

它会给你一个交互式界面，专门调 default、think、background 这些路由项。

九、这个环境变量一定要记住：`CLAUDE_CODE_ATTRIBUTION_HEADER=0`

这是整篇最像“血泪经验”的部分。

如果你在用第三方 AI 服务、模型网关、某些代理层，或者本地模型服务，建议你直接加上：

export CLAUDE_CODE_ATTRIBUTION_HEADER=0

1、它是干嘛的

社区里大量实际反馈都指向一件事：Claude Code 默认带上的 attribution / billing 相关标记，在某些第三方链路里会出问题。

常见表现有两种：

缓存命中变差：尤其是你依赖第三方服务的 prompt cache 或 KV cache 时，这类额外标记可能让请求不再稳定，缓存白白失效。
部分网关直接报错：尤其是某些 Bedrock、自建网关或兼容层，会对这类 header 或注入字段比较敏感。

你可以把它理解成一句大白话：

你明明只想换个模型后端，结果请求里多带了点“官方身份标记”，第三方链路不一定吃得消。

这时候把它关掉，世界往往会清净很多。

2、应该加到哪里

最简单的是加到你的 shell 配置：

export CLAUDE_CODE_ATTRIBUTION_HEADER=0

如果你希望 Claude Code 全局都带上，也可以写到 ~/.claude/settings.json：

{
  "env": {
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}

如果你只是在某个项目里临时使用，也可以写进项目的 .claude/settings.local.json。

3、什么时候优先怀疑它

如果你遇到下面这些现象，优先排查它：

第三方服务明明兼容，但 Claude Code 一直报奇怪的协议错误
接到本地模型后，缓存效果明显不对劲
Bedrock 或某些代理层报和 billing header、保留字段相关的错误

别一上来就怀疑模型。先把这个变量补上，很多时候问题就没了。

十、几个高频注意事项，能少踩很多坑

1、改完 `config.json` 记得 `ccr restart`

这个前面提过一次，但值得再提一次。

ccr restart

ccr 不会替你脑补“你刚才是不是改了配置”。不重启，很多改动就是不会生效。

2、CI / Docker / GitHub Actions 记得开非交互模式

如果你在自动化环境里跑，配置里建议带上：

{
  "NON_INTERACTIVE_MODE": true
}

否则有些环境会因为标准输入处理问题卡住，看起来像“莫名其妙不动了”。

3、不要把本地路由服务裸奔暴露出去

如果你设置了 HOST 和 APIKEY，那说明你准备让 ccr 监听更广的地址。

这时候一定要知道自己在干什么。

默认只监听本机，其实反而是最省心的。除非你确实要跨机器访问，不然别急着往 0.0.0.0 上挂。

4、日志很有用，出问题先看日志

ccr 的日志一般在：

~/.claude-code-router/logs/
~/.claude-code-router/claude-code-router.log

协议转换错了、路由没命中、请求出错，很多时候日志比你盲猜快得多。

5、Claude Code 本体和 `ccr` 不是一回事

很多新手会把这俩混在一起。

你可以这样记：

Claude Code 负责 Agent 体验
ccr 负责把请求导向你想去的模型服务

所以出问题时要先分层：

是 Claude Code 本体的问题？
是 ccr 路由的问题？
还是第三方模型服务本身的问题？

分层排查，效率会高很多。

十一、一套我更推荐的日常姿势

如果你想要一个比较顺手、长期可维护的用法，我更推荐这套：

1、先把公共环境变量配好

export MY_LLM_API_KEY="你的密钥"
export CLAUDE_CODE_ATTRIBUTION_HEADER=0

2、第一次用 `ccr ui` 把配置配明白

ccr ui

3、日常直接激活环境

eval "$(ccr activate)"

4、以后正常用 `claude`

claude

5、需要临时切模型时，用 `/model`

/model myproxy,reasoning-model

这套流程的好处是：你平时几乎感觉不到自己“在用一层路由器”，但该有的自由度一分都没少。

十二、最后给一句不那么官方的话

很多人第一次接触 ccr，会以为它只是“让 Claude Code 支持第三方模型”的小工具。

其实不是。

它真正有意思的地方在于：Claude Code 终于不再和某个单一模型入口绑死了。

从这一步开始，你可以把最贵的模型留给最难的活，把最便宜的模型扔给脏活累活，把长上下文交给长上下文擅长的家伙，把推理任务交给更会想的那个。

工具还是那把刀，但刀柄终于握回自己手里了。