# Claude Code 连接 OpenRouter 和 DeepSeek：路线选择、配置与首错排查

> 一份路线优先的 Claude Code OpenRouter / DeepSeek 配置手册：环境变量、模型名、/status、供应商日志、首错修复和免费承诺止损线。

- URL: https://blog.laozhang.ai/zh/posts/claude-code-openrouter-deepseek
- Published: 2026-07-03
- Updated: 2026-07-03
- Author: AI Free API Team (https://blog.laozhang.ai/zh/about)
- Category: Claude Code
- Tags: Claude Code, OpenRouter, DeepSeek, 开发者工具, API 配置

---
Claude Code 连接 OpenRouter 和 DeepSeek 时，第一步不是复制命令，而是先决定当前会话到底走哪条路。用 OpenRouter，表示 OpenRouter 负责网关、模型目录、供应商路由和活动记录；用 DeepSeek 直连，表示 DeepSeek 的 Anthropic-compatible 端点、token、模型 ID 和账单活动必须同时成立；用代理或路由器项目，则要把它当成实验路线，先证明 API 形状、日志、费用和数据路径都可解释。

| 路线 | 适合谁 | 测试前必须一致 |
| --- | --- | --- |
| OpenRouter 路线 | 希望由 OpenRouter 统一网关、供应商切换、模型目录和活动记录。 | OpenRouter 的 base URL、OpenRouter token、OpenRouter 模型名、OpenRouter 活动记录。 |
| DeepSeek 直连路线 | 明确要让 Claude Code 直接请求 DeepSeek 的 Anthropic-compatible API。 | DeepSeek 的 base URL、DeepSeek token、DeepSeek 模型 ID、DeepSeek 控制台或账单活动。 |
| 代理/路由器路线 | 在验证第三方 adapter、本地代理、团队网关或多模型切换逻辑。 | base URL、token、模型映射、日志、数据处理、费用证明都由同一个代理 owner 解释。 |

在真实仓库任务之前先停一下：<code>/status</code>、供应商活动记录和一个极小 canary prompt 必须指向同一个 owner。一个测试只允许一个 base URL、一个凭据 owner、一个模型 owner。只要三者不一致，就先回滚环境变量，不要继续叠新配置。

## 先选路由，再贴变量

最常见的失败并不是 Claude Code 缺少某条神秘命令，而是路由混用。比如 base URL 指到 OpenRouter，token 却来自 DeepSeek；模型名写成 DeepSeek 直连 ID，但当前 shell 仍有 Anthropic 登录或旧的 <code>ANTHROPIC_API_KEY</code>；代理接受了请求，却没有保留 Claude Code 期待的 Anthropic API 形状。表面上这些都像“模型不可用”，本质上是所有权不一致。

截至 2026-07-03 的资料核对，边界可以这样拆开：

| Owner | 它负责什么 | 它不能证明什么 |
| --- | --- | --- |
| Anthropic Claude Code 文档 | Claude Code 客户端行为、环境变量名、settings、<code>/status</code>、网关边界。 | Anthropic 支持所有第三方模型或代理行为。 |
| OpenRouter 文档 | OpenRouter 的 Claude Code 路线、token、base URL、模型命名、供应商活动。 | DeepSeek 直连 API 与 OpenRouter 路由行为完全相同。 |
| DeepSeek 文档 | DeepSeek Anthropic-compatible 端点、模型 ID、字段映射和兼容性说明。 | OpenRouter 供应商路由已经生效，或代理路线可靠。 |
| 代理/路由器项目 | 自己的 adapter、日志、成本、数据路径和兼容声明。 | Claude Code 官方支持、供应商费用或工具行为有一线保证。 |

OpenRouter 的 Claude Code cookbook 适合把 OpenRouter 作为网关 owner。DeepSeek 的 coding agent 与 Anthropic-compatible 文档适合把 DeepSeek 作为直连 owner。Anthropic 的 Claude Code 文档仍然负责客户端和网关接口边界。三者可以共同帮助你搭建路线，但不能互相替代。

## 清理冲突凭据

![Claude Code、OpenRouter、DeepSeek 与代理路线的环境变量所有权图](https://blog.laozhang.ai/posts/zh/claude-code-openrouter-deepseek/img/env-var-ownership-map.png)

配置 OpenRouter 或 DeepSeek 之前，先确认当前 shell 中有没有旧 owner。不要打印真实密钥，只检查变量是否存在：

    test -n "$ANTHROPIC_AUTH_TOKEN" && echo "ANTHROPIC_AUTH_TOKEN is set"
    test -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY is set"
    test -n "$ANTHROPIC_BASE_URL" && echo "ANTHROPIC_BASE_URL is set"
    test -n "$ANTHROPIC_MODEL" && echo "ANTHROPIC_MODEL is set"

如果结果和预期不一致，先找来源。它可能来自 shell profile、<code>.env</code> loader、终端启动器、devcontainer、CI secret，或者 <code>.claude/settings.local.json</code>。直接再 export 一层变量通常只会让问题变得更难解释。

需要干净测试时，先在当前 shell 清空路线变量：

    unset ANTHROPIC_AUTH_TOKEN
    unset ANTHROPIC_API_KEY
    unset ANTHROPIC_BASE_URL
    unset ANTHROPIC_MODEL

然后从同一个 shell 启动 Claude Code。测试只在“你检查过的环境”和“你启动 Claude Code 的环境”一致时才有意义。团队场景还要确认终端、IDE、任务运行器是否注入了额外变量。

## OpenRouter 路线怎么配

选择 OpenRouter 路线时，OpenRouter 要拥有整条网关路径。token 来自 OpenRouter，base URL 指向 OpenRouter，模型名按 OpenRouter 当前文档写，活动证明也要在 OpenRouter 的记录里出现。

临时 shell 测试可以是：

    export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
    export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
    unset ANTHROPIC_API_KEY
    claude
    /status

文档和团队脚本里只放占位符，不要把真实 key 写进共享文件或截图。这里最重要的不是某个固定模型名，而是 <code>ANTHROPIC_BASE_URL</code>、<code>ANTHROPIC_AUTH_TOKEN</code> 和模型 selector 都属于 OpenRouter 路线。

首次证明应该很小：新开一个 Claude Code 会话，运行 <code>/status</code>，发一个不会改文件的 canary prompt，再到 OpenRouter 活动记录里确认请求、模型和 provider 路径。如果 <code>/status</code> 和 OpenRouter 活动不一致，不要继续换模型名。先清空环境，重新从一个 owner 建路由。

## DeepSeek 直连路线怎么配

选择 DeepSeek 直连时，Claude Code 请求应直接落到 DeepSeek 的 Anthropic-compatible API。DeepSeek 负责端点、token、模型 ID、字段兼容说明和活动记录。OpenRouter 日志不能证明 DeepSeek 直连；它只能证明 OpenRouter 路线里可能使用了 DeepSeek provider。

一个 shell-scoped 测试可以是：

    export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
    export ANTHROPIC_AUTH_TOKEN="$DEEPSEEK_API_KEY"
    export ANTHROPIC_MODEL="deepseek-v4-pro[1m]"
    claude
    /status

DeepSeek 文档还列出过 coding-agent 模型选项，例如 <code>deepseek-v4-flash</code>。不要把模型 ID 当永久常量。可用性、后缀、web-search 行为、字段映射和价格都属于高波动 provider fact，写进团队 runbook 之前要再次核对。

DeepSeek 直连的证明负担和 OpenRouter 不一样。你要看到 DeepSeek 侧活动、DeepSeek 模型 ID、DeepSeek 端点和 Claude Code 会话状态彼此一致。只要其中一个环节指向 OpenRouter、Anthropic 或代理，当前测试就不是 DeepSeek 直连。

## 用 settings.local 防止 shell 漂移

shell export 很适合一次 canary，但不适合两天后继续复用。反复测试时，把路线变量放进本机、忽略提交的 local settings 更容易审计。

DeepSeek 直连可以使用这样的形状：

    {
      "env": {
        "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
        "ANTHROPIC_AUTH_TOKEN": "$DEEPSEEK_API_KEY",
        "ANTHROPIC_MODEL": "deepseek-v4-flash"
      }
    }

OpenRouter 也同样按 owner 保持一致：

    {
      "env": {
        "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
        "ANTHROPIC_AUTH_TOKEN": "$OPENROUTER_API_KEY",
        "ANTHROPIC_MODEL": "openrouter-model-id-from-current-docs"
      }
    }

不要盲目把这段复制到共享 <code>.claude/settings.json</code>。先确认 <code>.claude/settings.local.json</code> 被仓库忽略。token、私有 base URL、个人 provider 路线只适合 local scope；团队共享文件只放团队同意的行为，不放个人凭据。

## 真实任务前的验证循环

![Claude Code 后端路线验证循环](https://blog.laozhang.ai/posts/zh/claude-code-openrouter-deepseek/img/verification-loop.png)

验证不是出错后的补救，而是路线切换的一部分。一次后端切换只有在 route、credential、model 和 provider evidence 都一致时才算安全。

| 步骤 | 检查什么 | 通过条件 |
| --- | --- | --- |
| 1. 极小 prompt | 不读敏感文件、不改仓库的 canary。 | 会话能正常回答，没有 auth 或 tool 错误。 |
| 2. <code>/status</code> | Claude Code 认为当前账户、路线、模型是什么。 | 和你选择的 owner 一致。 |
| 3. 环境变量 | base URL、token owner、模型变量。 | 只存在目标路线所需变量。 |
| 4. 供应商活动 | OpenRouter 或 DeepSeek 的活动、日志、账单记录。 | 同一请求出现在正确 owner 名下。 |
| 5. 只读仓库动作 | 读取 package scripts、解释配置、运行版本命令。 | 行为正常，并且不会修改真实分支。 |
| 6. 回滚 | 清空变量、重启会话。 | 能回到之前已知路线。 |

如果切换原因是成本、可用性或模型选择，就更不能跳过供应商活动证明。<code>/status</code> 告诉你 Claude Code 认为自己在哪里，供应商活动告诉你请求实际到了谁那里。

## 第一条错误先分类

![Claude Code 使用 OpenRouter 和 DeepSeek 时的首错排查板](https://blog.laozhang.ai/posts/zh/claude-code-openrouter-deepseek/img/first-error-triage.png)

第一次失败时先分类，不要马上加更多变量。大多数失败都可以归到所有权错配。

| 症状 | 可能原因 | 第一修复 |
| --- | --- | --- |
| <code>401</code> 或 <code>403</code> | token 不属于 base URL owner，key 过期，或另一个凭据变量优先级更高。 | 清空路线变量，只设置一个 token owner，重启测试。 |
| <code>404</code>、model not found、模型不匹配 | 模型 ID 属于另一条路线，或 provider catalog 已变化。 | 从当前 route owner 文档取模型 ID，再看 provider 活动。 |
| provider dashboard 没有请求 | 请求没有到达你以为的供应商。 | 检查 <code>ANTHROPIC_BASE_URL</code>、shell 来源、旧登录或代理是否抢占。 |
| Claude Code 卡住或工具异常 | 代理兼容性不完整，header 或工具调用没有保留。 | 回到文档化路线，把代理单独测试。 |
| 费用出现在错误位置 | route owner 和 billing owner 被混在一起。 | 用 <code>/status</code> 加 provider activity 重新确认账单 owner。 |
| “免费”或“不限量”路线失败 | 当前 provider 没有证明这条承诺。 | 把它当作未验证营销话术，直到路线、模型和限制都有证据。 |

最快的恢复方式通常是回到空路线：

    unset ANTHROPIC_AUTH_TOKEN
    unset ANTHROPIC_API_KEY
    unset ANTHROPIC_BASE_URL
    unset ANTHROPIC_MODEL
    claude
    /status

回到已知状态后，再只加一个分支的变量。OpenRouter 分支失败就只排 OpenRouter 的 base URL、token、模型和活动；DeepSeek 直连失败就只排 DeepSeek 的端点、token、模型 ID 和活动。不要跨分支混合修复。

## 成本、数据和支持止损线

把成本放在第一承诺很危险。真正的第一承诺应该是可证明路线。价格、免费额度、供应商优先级、web-search 费用、模型可用性和 rate limit 都会变化。任何“free forever”“unlimited”“便宜 2%-5%”“任意模型都能用”的说法，在当前 route owner 没有证明前都不能写进团队规范。

| 止损线 | 原因 |
| --- | --- |
| 不把敏感代码发给未验证代理 | 你可能不知道谁记录 prompt、文件和工具输出。 |
| 不信没有当前证明的成本承诺 | OpenRouter 与 DeepSeek 价格、可用性和 provider 选择会变。 |
| 不把非 Claude 模型路由说成 Anthropic 官方支持 | Anthropic 负责 Claude Code 客户端边界，不负责每个 gateway 结果。 |
| 不提交 token 或私有 base URL | 共享 settings 不是凭据存放位置。 |
| 供应商活动证明前不跑真实编辑任务 | agent 改文件前必须有回滚路线。 |

如果问题其实是网关选型，就先做网关比较；如果问题是安装 CLI，就先处理安装；如果问题是另一个产品里的 DeepSeek，不要把那条产品路线混到 Claude Code gateway 设置里。

## 常见问题

### Claude Code 能同时使用 OpenRouter 和 DeepSeek 吗？

可以用两者，但不能在一次测试里混成一条路线。一次会话要么是 OpenRouter owner，要么是 DeepSeek 直连 owner，要么是代理 owner。base URL、token、模型和活动证明都必须指向同一个 owner。

### 应该通过 OpenRouter 用 DeepSeek，还是直连 DeepSeek？

需要 OpenRouter 的 provider 路由、模型目录、活动记录和网关行为时选 OpenRouter。需要 DeepSeek 自己的 Anthropic-compatible 端点、DeepSeek 模型 ID 和 DeepSeek 侧活动时选直连。更好的路线是你能为当前仓库、成本边界和支持 owner 证明的路线。

### Claude Code OpenRouter 或 DeepSeek 设置应该放哪里？

一次性 canary 用 shell 变量。本机长期实验可以用被忽略的 <code>.claude/settings.local.json</code>。不要把 provider token、私有 base URL 或个人模型选择放进共享 settings。

### <code>/status</code> 能证明什么？

它是客户端侧的第一检查点，能说明 Claude Code 当前认为自己在用什么账户、路线和模型。但它不能替代 provider activity。真实任务前要同时看环境变量和 OpenRouter 或 DeepSeek 的活动记录。

### 免费或不限量的 OpenRouter DeepSeek 路线可信吗？

只有当前 provider 证明时才可信。免费额度、无限承诺、供应商优先级和价格都属于高波动事实。可发布的团队手册应该写证明日期、owner 和回滚路径，而不是复述宣传语。

### 为什么模型名一直失败？

模型 ID 很可能属于另一条路线。OpenRouter 模型名、DeepSeek 直连模型 ID 和 Anthropic 模型别名不能互换。清空路线，只设置一个 owner，再按那个 owner 的当前文档核对模型。