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

# Claude Code

> 在 Claude Code CLI 中使用 Venice AI 的 Claude 模型

[Claude Code](https://docs.anthropic.com/en/docs/claude-code) 是 Anthropic 用于代理式编码的 CLI 工具。本指南将向您展示如何通过 Venice AI 运行它，以按 token 付费的方式访问 Claude Opus 4.5/4.6 和 Sonnet 4.5/4.6。

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

  <Card title="Claude 模型" icon="microchip">
    通过 Venice 访问 Opus 4.5/4.6 和 Sonnet 4.5/4.6
  </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">
    在 Claude Code 的出站请求到达 Anthropic 之前拦截它们
  </Step>

  <Step title="转换" icon="arrows-rotate">
    转换请求格式并映射模型 ID（例如 `claude-opus-4-5`）
  </Step>

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

***

## 前置条件

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

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

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

***

## 设置

<Steps>
  <Step title="安装 Claude Code">
    如果您尚未安装，请安装 Anthropic 的 Claude Code CLI：

    ```bash theme={"dark"}
    npm install -g @anthropic-ai/claude-code
    ```
  </Step>

  <Step title="安装路由器">
    ```bash theme={"dark"}
    npm install -g @musistudio/claude-code-router
    ```
  </Step>

  <Step title="获取您的 API 密钥">
    从 [venice.ai/settings/api](https://venice.ai/settings/api) 生成密钥。您将在下一步直接在配置文件中粘贴它。
  </Step>

  <Step title="创建配置">
    创建配置目录：

    ```bash theme={"dark"}
    mkdir -p ~/.claude-code-router
    ```

    然后使用您喜欢的编辑器创建 `~/.claude-code-router/config.json`：

    ```bash theme={"dark"}
    # Using nano
    nano ~/.claude-code-router/config.json

    # Or using VS Code
    code ~/.claude-code-router/config.json
    ```

    粘贴以下配置：

    ```json theme={"dark"}
    {
      "APIKEY": "",
      "LOG": true,
      "LOG_LEVEL": "info",
      "API_TIMEOUT_MS": 600000,
      "HOST": "127.0.0.1",
      "Providers": [
        {
          "name": "venice",
          "api_base_url": "https://api.venice.ai/api/v1/chat/completions",
          "api_key": "your-venice-api-key-here",
          "models": [
            "claude-opus-4-5",
            "claude-sonnet-4-5",
            "claude-opus-4-6",
            "claude-opus-4-6-fast",
            "claude-sonnet-4-6"
          ],
          "transformer": {
            "use": ["anthropic"]
          }
        }
      ],
      "Router": {
        "default": "venice,claude-opus-4-5",
        "think": "venice,claude-opus-4-5",
        "background": "venice,claude-opus-4-5",
        "longContext": "venice,claude-opus-4-5",
        "longContextThreshold": 100000
      }
    }
    ```

    <Note>
      如果您在路由器运行时修改 `config.json`，请使用 `ccr restart` 重启以应用变更。
    </Note>
  </Step>

  <Step title="启动">
    启动路由器，然后启动 Claude Code：

    ```bash theme={"dark"}
    ccr start
    ccr code
    ```

    或使用激活方式：

    ```bash theme={"dark"}
    eval "$(ccr activate)" && claude
    ```
  </Step>
</Steps>

***

## 支持的模型

| 模型                   | Venice ID              | 最适合       |
| -------------------- | ---------------------- | --------- |
| Claude Opus 4.5      | `claude-opus-4-5`      | 复杂推理、大型重构 |
| Claude Sonnet 4.5    | `claude-sonnet-4-5`    | 快速迭代、日常编码 |
| Claude Opus 4.6      | `claude-opus-4-6`      | 复杂推理、大型重构 |
| Claude Opus 4.6 Fast | `claude-opus-4-6-fast` | 低延迟的复杂推理  |
| Claude Sonnet 4.6    | `claude-sonnet-4-6`    | 快速迭代、日常编码 |

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

***

## 路由器功能

路由器除了基本路由外还提供多个有用功能：

<AccordionGroup>
  <Accordion title="即时切换模型">
    在 Claude Code 内部使用 `/model` 命令可在不重启的情况下切换模型：

    ```
    /model venice,claude-sonnet-4-5
    ```

    当您希望用 Opus 处理复杂任务、用 Sonnet 进行快速迭代时非常有用。
  </Accordion>

  <Accordion title="使用 UI 模式进行可视化配置">
    更喜欢图形界面？启动基于 Web 的配置编辑器：

    ```bash theme={"dark"}
    ccr ui
    ```

    这将打开一个浏览器界面来编辑您的 `config.json`，无需直接接触文件。
  </Accordion>

  <Accordion title="路由器场景说明">
    `Router` 配置部分控制哪种模型处理不同类型的任务：

    | 场景            | 何时使用                                  |
    | ------------- | ------------------------------------- |
    | `default`     | 通用请求                                  |
    | `think`       | 推理密集型任务（Plan Mode）                    |
    | `background`  | 后台操作                                  |
    | `longContext` | 当上下文超过 `longContextThreshold` token 时 |

    您可以将不同场景路由到不同的模型。例如，对于后台任务使用 Sonnet 以节省成本。
  </Accordion>

  <Accordion title="使用日志进行调试">
    如果出现问题，请检查日志：

    ```bash theme={"dark"}
    # Server logs (HTTP, API calls)
    ~/.claude-code-router/logs/ccr-*.log

    # Application logs (routing decisions)
    ~/.claude-code-router/claude-code-router.log
    ```

    在配置中设置 `"LOG_LEVEL": "debug"` 以获得更详细的输出。
  </Accordion>
</AccordionGroup>

***

## 缓存行为

Venice 的 [prompt 缓存](/guides/features/prompt-caching) 与 Claude Code 原生的缓存标记协同工作。Venice 会自动检测 Claude Code 何时发送 `cache_control` 字段，并相应调整其缓存策略。

| 场景                          | 缓存 TTL | 由谁控制                 |
| --------------------------- | ------ | -------------------- |
| 默认（推荐）                      | 5 分钟   | Claude Code + Venice |
| 使用 `cleancache` transformer | 1 小时   | 仅 Venice             |

<AccordionGroup>
  <Accordion title="何时不使用 cleancache（大多数用户）">
    默认配置让两个系统协同工作：

    * Claude Code 发送其原生的 `cache_control` 标记
    * Venice 在其周围添加 5 分钟 TTL 的缓存
    * 两个系统共享 4 块缓存限制

    这非常适合您频繁请求的活跃编码会话。
  </Accordion>

  <Accordion title="何时使用 cleancache">
    在以下情况下，将 `cleancache` 添加到 transformer：

    * 您遇到 4 块缓存限制错误
    * 出现奇怪的缓存行为
    * 您希望 Venice 在更长的会话中使用 1 小时 TTL

    ```json theme={"dark"}
    "transformer": {
      "use": ["anthropic", "cleancache"]
    }
    ```

    这会剥离 Claude Code 的缓存标记，让 Venice 以更长的 TTL 完全控制。
  </Accordion>
</AccordionGroup>

***

## 资源

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

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