CCR 配置梳理：先快速跑通，再理解它是怎么接管 Claude Code 的
我现在对 CCR 的最小结论很简单：
1. 先配置 CCR
2. 启动 CCR 服务
3. 用 ccr code 启动 Claude Code
4. Claude Code 的请求才会真正走 CCR
5. 改了配置以后要重启 CCR
官方 Quick Start 给出的基本顺序也是这个思路：先配置 Router，再执行 ccr start 启动服务，最后用 ccr code 使用 Claude Code。修改配置后需要 ccr restart 让配置生效。(Musistudio)
一、快速上手：我自己回顾时直接照着做
第 1 步：先配好 CCR
CCR 的配置文件位置在：
~/.claude-code-router/config.json
官方文档说明，CLI 和 Server 共用这一个配置文件，也可以通过 Web UI 进行配置。(Musistudio)
我一般会先记住两种配置方式：
方式 1：直接改 ~/.claude-code-router/config.json
方式 2：运行 ccr ui，在网页里配
如果只是想先跑通，最简单的入口就是：
ccr ui
这个命令会打开 Web UI，你可以在里面配置 provider、model、路由规则。(Musistudio)
第 2 步：启动 CCR 服务
配置完以后，先启动 CCR：
ccr start
ccr start 的作用是启动 Claude Code Router 服务。官方命令页也给出了可选参数，比如自定义端口、指定配置文件、后台运行、设置日志级别。(Musistudio)
我对这一步的理解很朴素：
ccr start = 把 CCR 这个中间层先开起来
第 3 步：一定要用 ccr code 启动 Claude Code
这是我一开始最容易误解的地方。
我原先以为只要 ccr start 了，Claude Code 就会自动被 CCR 接管。
后来才想明白，事情没有这么简单。
官方 Quick Start 写得很清楚，启动 Router 以后，要这样用 Claude Code：
ccr code
这一步之后，请求才会通过 Claude Code Router 转发到你配置的 provider。ccr code [args...] 在命令页里的定义也是“通过 router 执行 claude 命令”。(Musistudio)
所以我现在给自己记成下面这样：
ccr start = 启动 CCR 服务
ccr code = 让 Claude Code 走 CCR
这两步缺一块，理解上就会歪。
第 4 步：改了配置以后重启
改完 config.json，或者在 UI 里改完配置以后，要执行：
ccr restart
官方文档明确写了，修改配置文件或者通过 Web UI 改配置后，都要重启服务，或者在 Web UI 里直接执行保存并重启。(Musistudio)
这一步很好记：
配完不重启 = 白改
第 5 步：不用了就停掉
停止 CCR：
ccr stop
官方命令页对 ccr stop 的说明很直接，就是停止当前运行中的服务。(Musistudio)
二、我自己常用的一组命令
为了回顾更快，我把最常用的命令直接记在这里。
1）打开配置界面
ccr ui
作用：打开 Web UI。(Musistudio)
2）启动服务
ccr start
作用：启动 CCR 服务。默认支持 --port、--config、--daemon、--log-level 等参数。(Musistudio)
3）启动走 CCR 的 Claude Code
ccr code
作用：通过 CCR 执行 Claude Code。只有这一步做了，Claude Code 才会真正走你配好的路由。(Musistudio)
4）配置改完后重启
ccr restart
作用：重启 CCR 服务，让新的配置生效。(Musistudio)
5）停止服务
ccr stop
作用：停止 CCR 服务。(Musistudio)
6）可选：导出环境变量
ccr activate
官方命令页对它的描述是输出 shell 环境变量，用于和外部工具集成。这个命令我目前主要把它当扩展入口，核心路径还是 ccr start 加 ccr code。(Musistudio)
三、一个最短的上手流程
我现在自己会这样记：
[先配置]
│
├─ 改 ~/.claude-code-router/config.json
│
└─ 或者执行 ccr ui
[再启动]
│
└─ ccr start
[再进入 Claude Code]
│
└─ ccr code
[改配置以后]
│
└─ ccr restart
[不用了]
│
└─ ccr stop
只看操作层面，其实 CCR 没那么绕。 真正容易绕晕人的，是后面的运行逻辑。
四、我后来才真正想明白的核心逻辑
到这里开始讲原理。
我后来想清楚 CCR，靠的是一个非常朴素的理解：
CCR 是一个接管 Claude Code 请求的中间层。 Claude Code 先把请求交给 CCR，CCR 再根据配置，把请求发给合适的模型或后端。
这个思路和官方 Quick Start 是一致的。Quick Start 明确写到，ccr code 之后，请求会通过 Claude Code Router 路由到已配置的 provider。(Musistudio)
把这个主线放进脑子里以后，UI 和 config.json 都会好懂很多。
五、先看整条链路
我现在理解的完整链路是这样的：
[你执行命令]
│
├─ ccr ui
│ │
│ └─ 打开配置界面
│
├─ ccr start
│ │
│ └─ 启动 CCR 服务
│
└─ ccr code
│
└─ 启动走 CCR 的 Claude Code
│
▼
[Claude Code 发请求]
│
▼
[CCR]
│
│ 按配置判断请求该走哪类模型
▼
[模型后端 / API]
│
▼
[CCR]
│
▼
[Claude Code 显示结果]
这张图里最重要的点只有一个：
不是开了 CCR 就自动接管了 Claude Code
而是要通过 ccr code 进入 Claude Code，接管链路才真正成立
为了避免以后自己再绕进去，我现在直接把“ccr start 和 ccr code 是两件事”写死在脑子里。
六、CCR UI 右边那些分类，我现在怎么理解
我之前最看不懂的，就是 UI 右边那一排选项。
后来想通了，这些东西本质上都是在回答一个问题：
这类请求，应该交给哪个模型处理？
可以把它理解成下面这样：
[Claude Code 发来请求]
│
▼
[CCR 接管请求]
│
▼
[判断这次请求的类型]
┌────────────┬────────────┬────────────┬────────────┐
▼ ▼ ▼ ▼
[思考类] [长上下文类] [图片类] [通用类]
│ │ │ │
▼ ▼ ▼ ▼
[推理模型A] [长上下文模型B] [视觉模型C] [默认模型D]
└────────────┴────────────┴────────────┴────────────┘
│
▼
[结果返回 CCR]
│
▼
[返回 Claude Code]
这张图就是我现在对 CCR UI 的理解。
以前我觉得那些分类像备注。 现在我知道，它们实际上是路由规则。
CCR 接到请求以后，会根据规则把它分发出去。 所以那些“思考、长上下文、图片、通用”不是摆设，它们决定了请求最后去找谁。
七、config.json 到底在控制什么
我现在会把 config.json 粗略拆成两层来看。
第一层：服务入口
这一层解决的是：
CCR 自己监听在哪里
谁能连进来
常见字段包括：
HOST
PORT
APIKEY
官方 Basic Configuration 给了常见示例，比如：
{
"HOST": "127.0.0.1",
"PORT": 3456
}
也说明了 APIKEY 可以用于保护服务。(Musistudio)
第二层：模型路由
这一层解决的是：
请求进来以后，应该发给谁
官方文档给出的 Router 配置示例里，已经能看到 default、background、think、longContext 这类路由项。(Musistudio)
我现在会把它记成这个结构：
[config.json]
│
├─ HOST → 监听地址
├─ PORT → 监听端口
├─ APIKEY → 访问保护
├─ Providers → 有哪些后端
├─ models → 这些后端支持哪些模型
└─ Router → 不同类型请求走哪个模型
这个角度一建立，配置文件就不会再像一锅粥。
八、我对 HOST、PORT、APIKEY 的理解
1）HOST
官方 Basic Configuration 里给了 HOST 和 PORT 的示例。HOST 就是监听地址。(Musistudio)
我自己会这样记：
HOST = 127.0.0.1
│
└─ 仅本机访问
HOST = 0.0.0.0
│
└─ 允许其他机器访问
如果只是本机自己调试，127.0.0.1 更省心。
如果你要让局域网主机、WSL、其他机器来访问 CCR，才会考虑放到 0.0.0.0。
2）PORT
PORT 决定监听端口。官方文档里有两种常见写法：
一类是在 Quick Start 和 ccr start 命令页，默认示例是 8080。
另一类是在 Basic Configuration 的常见配置示例里，给的是 127.0.0.1:3456。(Musistudio)
所以这里我不建议把端口死记成某一个值。 更稳的做法是看两样东西：
1. 你自己的 config.json
2. ccr start 启动后的实际输出
3）APIKEY
官方文档里把 APIKEY 描述为“可选，用于保护服务”。(Musistudio)
这里我补一条我自己的实践规则：
只要 HOST = 0.0.0.0
我就把 APIKEY 当成必须配置
这不是我在抠字眼，这是为了少给自己留坑。 服务开放给其他机器访问时，不做鉴权很危险。 所以这条我直接当硬规则执行。
九、为什么我之前会看不懂 CCR
因为我一开始老是在看“字段”，没有先看“流向”。
比如：
- 看见
ccr ui，只觉得它是个配置界面 - 看见
ccr start，只觉得它是启动服务 - 看见
config.json，只觉得是一堆字段 - 看见思考、长上下文、图片、通用，只觉得像分类标签
这些点单看都认识，连起来就迷路。
后来我换了个顺序：
先看请求从哪里来
再看 CCR 在中间做什么
最后再看配置文件怎么把这些行为落地
顺序一改，整套东西一下就顺了。
十、我现在给自己的最小认知模型
为了以后快速回忆，我现在把 CCR 简化成下面几句话：
1. ccr ui / config.json 用来配置规则
2. ccr start 用来启动 CCR
3. ccr code 用来让 Claude Code 走 CCR
4. CCR 负责接管请求并按类型分流
5. 具体模型后端负责真正回答
6. 修改配置后要 ccr restart
这六句话已经足够把 CCR 的主线钉住。
十一、我自己的结论
我现在再看 CCR，已经不再从“UI 好复杂”或者“config.json 好乱”开始看了。
我现在先看的是：
谁在发请求
谁在接请求
谁在做路由
谁在真正回答
顺着这条主线，CCR 的本质就很清楚了：
CCR 是 Claude Code 和具体模型后端之间的中间层。 它先接管请求，再根据配置把不同类型的请求路由到对应模型。
而真正让这条链路成立的关键动作，是这两个命令：
ccr start
ccr code
前者把路由服务开起来。 后者才让 Claude Code 真正走进这条链路里。(Musistudio)
十二、后面我还想继续补的内容
这篇先把主线理顺。 下一步我想继续补几块：
1. 一份我自己能直接看懂的 config.json 注释版
2. CCR UI 各个区域和配置文件字段的对应关系
3. 本地模型接入 CCR 的实际示例
4. 常见报错和排查顺序
5. Claude Code、CCR、本地模型三者联调时的完整链路
结尾
我觉得 CCR 最容易把人绕进去的地方，就是一开始就盯着配置项看。 这样看，很容易像站在迷宫里研究砖缝。
我现在回头总结，最该先记住的其实只有这句：
先配置
再 ccr start
再 ccr code
Claude Code 的请求才会真正经过 CCR
这句记住了，后面的 UI、路由和 config.json 才会越看越顺。