# cc-VisionRouter：让非多模态模型在Claude Code中安全处理长程任务的透明代理方案

> cc-VisionRouter是一款专为Claude Code设计的透明代理工具，通过智能分流机制自动将含图片的请求路由到多模态模型，避免非多模态主力模型因无法处理图像而崩溃，让开发者能够安心使用第三方模型执行长程任务。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-03T17:11:22.000Z
- 最近活动: 2026-06-03T17:19:09.858Z
- 热度: 161.9
- 关键词: Claude Code, 多模态模型, 透明代理, LLM路由, 长程任务, 第三方API, Anthropic API, 智能分流, AI工具链
- 页面链接: https://www.zingnex.cn/forum/thread/cc-visionrouter-claude-code
- Canonical: https://www.zingnex.cn/forum/thread/cc-visionrouter-claude-code
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：Able-rip
- 来源平台：GitHub
- 原始标题：cc-VisionRouter
- 原始链接：https://github.com/Able-rip/cc-VisionRouter
- 来源发布时间/更新时间：2026-06-03

## 背景：长程任务中的多模态痛点

在使用Claude Code配合第三方API（如mimo、各类国产或自建模型）执行开发任务时，尤其是**长程任务**场景，开发者经常会遇到一个令人头疼的问题：任务跑到一半突然中断，系统提示"There's an issue with the selected model..."。

这个问题的根源往往不是模型本身不存在或没有访问权限，而是**主力模型不支持多模态能力**。当上下文中混入任何图片——无论是用户粘贴的截图、工具返回的图像，还是`/compact`压缩历史时扫到的早期图片——请求就会带着图片数据发送给一个无法解析图像的模型，导致会话直接崩溃。

对于短对话来说，重开一把尚可接受。但对于已经积累了几十轮对话、数十万token的长程任务，这种中断是毁灭性的：上下文无法自动续接，所有进度付诸东流。这是所有希望使用第三方模型运行自主代理或长任务开发者的共同噩梦。

## 核心解决方案：智能分流机制

cc-VisionRouter的核心设计思路是**按内容类型智能分流**。它作为Claude Code与上游API之间的透明代理，不改变用户的工作流程，只做一件事——检查每个请求是否包含图片，然后决定将其路由到哪个模型：

```
Claude Code → cc-VisionRouter → 上游 API
                    │
          ├─ 含图片/文档     → 多模态模型（用户指定）
          ├─ 背景/压缩任务   → 多模态模型（历史里可能有图）
          └─ 其余纯文本      → 主力模型
```

这种分流机制带来了几个关键优势：

**日常编码零改变**：开发者可以继续使用最强或最经济的主力模型进行日常编码工作，无需任何调整。

**图片自动分流**：当请求中包含图片时，自动路由到多模态模型处理，主力模型永远不会"看到"它无法理解的内容。

**长任务安全压缩**：在执行`/compact`压缩含图历史时，也会自动使用多模态模型，避免在自动压缩环节因图片处理而崩溃。

**无需手动切换**：全程不需要手动执行`/model`切换模型，代理自动处理模型名翻译、`[1m]`后缀处理以及settings文件的改写与还原。

## 技术实现细节

### 背景任务的特殊处理

Claude Code的后台请求（如`/compact`、对话压缩、总结等，通常使用haiku档模型）是在整段对话历史上运行的，而历史记录中可能包含图片。如果将这些请求发送给不支持图片的主力模型，会导致报错甚至会话崩溃。因此，cc-VisionRouter会将背景/haiku请求也路由到视觉模型（多模态、通常更轻量），既保证了安全性又节省了token消耗。

背景请求的识别是自动进行的，代理会探测Claude Code的haiku/small-fast模型名，无需用户额外配置。

### 模型名自动改写

Claude Code发送的请求中的`model`字段会被直接替换为用户配置中的真实模型ID，再转发给上游API。这意味着用户无需关心Claude Code端配置的模型名与上游真实model ID之间的不一致问题，代理完全屏蔽了这一层差异。

### 后缀自动剥离

许多ccswitch或国产1M模型的配置中，模型名带有`[1m]`后缀（如`mimo-v2.5-pro[1m]`）。Claude Code会对这类后缀进行客户端校验，如果上游不认识就会直接报错。cc-VisionRouter在`start`时会自动将`~/.claude/settings.json`中模型字段的`[...]`标记剥离（原值已备份，`stop`时还原）。

## 安装与使用

该工具要求Node.js ≥ 18（使用原生fetch和Web Streams API）。

**全局安装（推荐）**：
```bash
npm install -g cc-visionrouter
cc-visionrouter
```

**从GitHub直接安装（始终最新）**：
```bash
npm install -g github:Able-rip/cc-VisionRouter
```

**基本命令**：
```bash
cc-visionrouter           # 交互式菜单
cc-visionrouter config    # 配置模型
cc-visionrouter start     # 启动代理
cc-visionrouter stop      # 停止代理
cc-visionrouter status    # 查看状态
cc-visionrouter logs      # 查看日志
```

配置过程中支持`← 返回上一级`和`Esc`返回操作。配置完成后会自动使用最小请求（`max_tokens:1`）测试baseUrl、API key和model是否真正可用，测试通过后才允许保存，避免配置错误导致代理无法运行。

## 内置预设配置

| 预设 | 主力模型 | 视觉模型 |
|------|----------|----------|
| 从Claude Code导入 | 从已配置模型中选择 | 同左 |
| mimo | mimo-v2.5-pro | mimo-v2.5 |
| Claude | claude-opus-4 | claude-sonnet-4 |
| 自定义 | 手动配置 | 手动配置 |

## 协议兼容性与限制

该工具是**Anthropic Messages API**（`/v1/messages`）的透明代理，只修改`model`字段进行路由，其余内容原样转发。

**支持的API**：
- Anthropic官方API
- 提供Anthropic兼容端点的网关（如小米MiMo `/anthropic`、OpenRouter等）

**不支持的API**：
- OpenAI格式上游（`/v1/chat/completions`）
- DeepSeek、SiliconFlow、智谱BigModel、阿里DashScope的默认API（除非它们另外提供了Anthropic兼容端点）

鉴权时会同时发送`x-api-key`和`Authorization: Bearer`，以兼容两类网关。

## 实际应用场景与价值

对于希望使用国产或自建模型替代Claude官方API的开发者来说，cc-VisionRouter解决了一个关键障碍：多模态能力的缺失不再意味着长程任务的不可行性。

在实际开发中，开发者经常需要向AI展示截图、设计稿或错误信息图片。如果没有多模态支持，这些场景就无法在纯文本模型上运行。而cc-VisionRouter让开发者可以继续使用性价比高、响应速度快的纯文本主力模型处理大部分工作，只在必要时才调用多模态模型处理图像，实现了成本与功能的最佳平衡。

更重要的是，它消除了长程任务中的"定时炸弹"——你不知道什么时候上下文里会突然混入一张图片导致整个会话崩溃。有了cc-VisionRouter，开发者可以专注于任务本身，而不必担心模型能力的边界问题。

## 总结与展望

cc-VisionRouter代表了一种务实的解决方案：不是等待所有模型都具备多模态能力，而是通过智能代理层在现有技术条件下解决问题。这种思路对于AI工具链的构建具有启发意义——在模型能力逐步完善的过程中，通过巧妙的工程手段填补能力鸿沟，让开发者能够更早地享受到新技术带来的效率提升。

随着越来越多的第三方模型开始提供多模态能力，cc-VisionRouter这样的工具可能会逐渐淡出历史舞台。但在当前阶段，它确实为那些希望在Claude Code中使用非多模态模型执行复杂长程任务的开发者提供了一个可靠的安全网。