> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-de47a659.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> 通过 claude-code-router 将 Claude Code CLI 路由到 Venice，按 token 付费使用 Claude 与 Fable 编码模型。

[Claude Code](https://code.claude.com/docs) 是 Anthropic 用于代理式编码的 CLI 工具。本指南将向您展示如何通过 Venice 运行它，以匿名化、按 token 付费的方式访问 Claude 模型。

<CardGroup cols={3}>
  <Card title="按 token 付费" icon="coins">
    无需订阅。仅按用量付费
  </Card>

  <Card title="Claude 模型" icon="cpu">
    通过 Venice 访问当前的 Opus、Sonnet 和 Fable 模型
  </Card>

  <Card title="Prompt 缓存" icon="bolt">
    Venice 缓存与 Claude Code 协同工作
  </Card>
</CardGroup>

## 为何需要路由器

Claude Code 默认直接连接 Anthropic 的 API。要将它与 Venice 一起使用，您需要 [claude-code-router](https://github.com/musistudio/claude-code-router) —— 一个开源本地代理：

<Steps>
  <Step title="拦截" icon="hand-stop">
    在 Claude Code 的出站请求到达 Anthropic 之前拦截它们
  </Step>

  <Step title="转换" icon="refresh">
    将 Anthropic Messages 请求转换为 Venice 的 OpenAI 兼容聊天格式
  </Step>

  <Step title="重定向" icon="route">
    将请求转发到 `api.venice.ai/api/v1/chat/completions`
  </Step>
</Steps>

***

## 前置条件

<CardGroup cols={3}>
  <Card title="Venice 账户" icon="user" href="https://venice.ai/settings/api?utm_source=venice-api-documentation">
    带 Venice 额度
  </Card>

  <Card title="Node.js" icon="brand-nodejs" href="https://nodejs.org/">
    v22 或更高
  </Card>

  <Card title="Claude Code" icon="terminal" href="https://code.claude.com/docs">
    通过 npm 安装
  </Card>
</CardGroup>

***

## 设置

<Steps>
  <Step title="安装或更新 Claude Code">
    安装最新的 Claude Code CLI：

    ```bash theme={null}
    npm install -g @anthropic-ai/claude-code@latest
    claude --version
    ```
  </Step>

  <Step title="安装 Claude Code Router">
    ```bash theme={null}
    npm install -g @musistudio/claude-code-router@latest
    npm list -g @musistudio/claude-code-router --depth=0
    ```
  </Step>

  <Step title="获取您的 API 密钥">
    从 [venice.ai/settings/api](https://venice.ai/settings/api?utm_source=venice-api-documentation) 生成密钥。您将在下一步将它添加到 CCR。
  </Step>

  <Step title="将 Venice 添加为提供商">
    启动 CCR 的管理界面：

    ```bash theme={null}
    ccr ui
    ```

    在 **Providers** 页面，选择 **Add provider**，然后选择 **Other / custom API endpoint**。输入：

    * **Name:** `Venice`
    * **API endpoint:** `https://api.venice.ai/api/v1`
    * **API key:** 您的 Venice API 密钥

    CCR 应会自动检测到 **OpenAI Chat**。如果没有，请打开 **Advanced settings**，关闭自动协议检测，并选择 **OpenAI Chat**。

    使用 **Search models** 或 **Custom models** 添加您需要的 Claude 模型，然后运行 **Check Connection** 并保存该提供商。连接检查会发送一个输出限制为一个 token 的真实请求。
  </Step>

  <Step title="创建 Claude Code 配置文件">
    在 **Agent Config** 中，选择 **Add profile**，然后选择 **Claude Code**：

    * 将配置文件命名为 `Claude Code - Venice`。
    * 测试期间将 **Effect scope** 保持为 **Only opened from CCR**。
    * 选择 **CLI only** 或 **CLI & APP**。
    * 将 **Model** 设置为 Venice 模型，例如 `Venice/claude-opus-4-8`。
    * 如果希望 Claude Code 的每个层级都使用 Venice，请将可选的 Fable、Opus、Sonnet 和 Haiku 模型字段也设置为 Venice 模型。

    保存配置文件。
  </Step>

  <Step title="启动并验证">
    按名称启动配置文件：

    ```bash theme={null}
    ccr "Claude Code - Venice"
    ```

    在 Claude Code 中：

    1. 运行 `/context` 并确认上下文窗口与所选模型匹配。对于 `claude-opus-4-8`，应显示 `1M`。
    2. 如果想切换到其他 Venice 模型，请运行 `/model`；1M 变体会标记为 **1M context**。
    3. 发送一条测试消息，然后在 CCR 中检查 **Request logs** 以确认请求使用了 Venice。
  </Step>
</Steps>

***

## 支持的模型

| 模型                   | Venice ID              | 上下文  |
| -------------------- | ---------------------- | ---- |
| Claude Fable 5.1     | `claude-fable-5-1`     | 1M   |
| Claude Fable 5       | `claude-fable-5`       | 1M   |
| Claude Opus 5        | `claude-opus-5`        | 1M   |
| Claude Opus 5 Fast   | `claude-opus-5-fast`   | 1M   |
| Claude Opus 4.8      | `claude-opus-4-8`      | 1M   |
| Claude Opus 4.8 Fast | `claude-opus-4-8-fast` | 1M   |
| Claude Opus 4.7      | `claude-opus-4-7`      | 1M   |
| Claude Opus 4.6      | `claude-opus-4-6`      | 1M   |
| Claude Opus 4.5      | `claude-opus-4-5`      | 198K |
| Claude Sonnet 5      | `claude-sonnet-5`      | 1M   |
| Claude Sonnet 4.6    | `claude-sonnet-4-6`    | 1M   |
| Claude Sonnet 4.5    | `claude-sonnet-4-5`    | 198K |

模型目录会随时间变化。请使用 CCR 中的 **Search models** 或 [`GET /models?type=text`](/api-reference/endpoint/models/list) 获取当前列表和限制。

<Info>
  Claude Code 针对 Claude 模型进行了优化。虽然 Venice 提供的其他模型（GPT、DeepSeek、Grok 等）可能可用，但由于 Claude Code 依赖 Claude 特有的功能（如扩展思考），我们无法保证同等体验。对于其他模型，请考虑使用 Venice 的[标准 API](/api-reference/endpoint/chat/completions)。
</Info>

***

## 更新现有安装

在排查现有安装的问题之前，请先更新 CCR：

```bash theme={null}
npm install -g @musistudio/claude-code-router@latest
npm list -g @musistudio/claude-code-router --depth=0
ccr ui
```

当前的 CCR 版本将实时配置存储在 `~/.claude-code-router/config.sqlite` 中。当该数据库不存在时，会导入旧的 `config.json`。迁移完成后，请通过 `ccr ui` 进行更改，而不要继续编辑 `config.json`。

如果更新后仍有后台进程在运行，请重启它：

```bash theme={null}
ccr stop
ccr start
```

***

## Prompt 缓存

Venice 的 [prompt 缓存](/guides/features/prompt-caching)与 Claude Code 原生的缓存标记协同工作。常规设置无需额外的缓存 transformer。

***

## 故障排除

<AccordionGroup>
  <Accordion title="上下文过早达到 100% 或压缩失败">
    1. 使用 `npm install -g @musistudio/claude-code-router@latest` 更新 CCR。
    2. 从 CCR 配置文件启动一个新的 Claude Code 会话。
    3. 运行 `/model` 并选择标记为 **1M context** 的 Venice 条目。
    4. 运行 `/context` 并确认窗口为 `1M`，而不是 `200K`。

    较旧的 CCR 版本可能无法向 Claude Code 暴露正确的上下文窗口或 token 用量。
  </Accordion>

  <Accordion title="CCR 在启动时崩溃">
    确认 Node.js 为 22 或更新版本，并更新 CCR：

    ```bash theme={null}
    node --version
    npm list -g @musistudio/claude-code-router --depth=0
    ```

    使用 `ccr serve` 在前台运行以暴露原始启动错误。来自 `server.logger.error` 的 `Cannot read properties of undefined (reading 'error')` 堆栈表明 CCR 安装已过时；请先更新再继续排查。
  </Accordion>

  <Accordion title="Claude Code 报告 ConnectionRefused">
    启动网关并验证其健康状态：

    ```bash theme={null}
    ccr start
    curl http://127.0.0.1:3456/health
    ```

    健康检查失败意味着本地 CCR 网关不可用；请求尚未到达 Venice。
  </Accordion>

  <Accordion title="配置更改被忽略">
    打开 `ccr ui` 并在其中进行更改。当前的 CCR 版本将配置存储在 `config.sqlite` 中；`config.json` 仅作为旧安装的迁移来源。
  </Accordion>
</AccordionGroup>

***

## 资源

<CardGroup cols={3}>
  <Card title="Venice API 文档" icon="book" href="/api-reference/api-spec">
    完整 API 参考
  </Card>

  <Card title="claude-code-router" icon="brand-github" href="https://github.com/musistudio/claude-code-router">
    源代码与 issues
  </Card>

  <Card title="CCR 版本发布" icon="history" href="https://github.com/musistudio/claude-code-router/releases">
    当前版本与发布说明
  </Card>
</CardGroup>