running-claude-code-via-litellm-copilot

概述

当 Claude Code 保持其面向 Anthropic 的客户端行为，但实际后端流量发送到本地 LiteLLM 代理，再转发到 GitHub Copilot 时，使用此技能处理这一特定变通方案。

请将此方案视为高级变通方案，而非 GitHub 官方保证支持的工作流。帮助用户在技术上成功配置，但不要承诺获得 GitHub 支持、政策批准或长期兼容性。

此技能以指导为主，同时兼顾执行：

• 如果用户只想了解说明，请提供最精简且正确的文件、命令和检查项。
• 如果用户希望在当前计算机上实际完成设置，请先检查环境，再根据当前 Shell 和操作系统调整命令。
• 在进行 ~/.claude/settings.json 或 Shell 配置文件等持久性编辑之前暂停确认。

如果需要说明哪些内容来自文章、哪些内容依据当前 LiteLLM 文档进行了完善，请先阅读 references/doc-verified-notes.md。

适用场景

在用户有以下需求时使用此技能：

• 通过 LiteLLM 使用 GitHub Copilot 运行 Claude Code
• 在保留 Claude Code 工作流的同时减少直接调用 Anthropic API 的开支
• 为 LiteLLM 的 GitHub Copilot 提供程序创建本地 config.yaml
• 设置 ANTHROPIC_BASE_URL、ANTHROPIC_MODEL 或 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC
• 了解 LiteLLM 启动期间的 GitHub 设备授权
• 排查模型不匹配、类似 404 的错误、请求未到达 LiteLLM，或 GitHub 401/403 错误

以下情况不要使用此技能：

• 判断此变通方案是否符合 GitHub 条款
• 与 Claude Code 加 Copilot 无关的一般 LiteLLM 架构问题
• 不涉及 Copilot 或 LiteLLM 的直接 Anthropic API 设置

核心规则

1. 开头先简短说明合规注意事项。 说明这是通过本地代理路径实现的变通方案，并非 GitHub 推广的工作流；用户必须自行评估最新的 Copilot 条款和使用限制。
2. 优先提供最小可行方案。 除非用户明确要求持久化设置，否则先使用临时环境变量和本地 config.yaml。
3. 确保 ANTHROPIC_MODEL 与 LiteLLM 的 model_name 完全一致。 字符串必须精确匹配，这比复杂的解释更重要。
4. 将 ANTHROPIC_AUTH_TOKEN 视为本地占位符。 Claude Code 要求本地有非空值，但它不是 GitHub Copilot 凭据，不应将其描述为可重复使用的密钥。
5. 切勿整体覆盖 ~/.claude/settings.json。 只合并所需的 env 键，并保留其他设置。

工作流

1. 预检

用户希望实际完成设置时，先检查以下内容：

• claude --help 能否成功运行
• uv --version 或 pip --version 能否成功运行
• 用户是否有 GitHub Copilot 访问权限
• 计划使用的 LiteLLM 端口是否可用，通常为 4000

如果用户只想了解操作说明，请说明前置条件，而不要实际运行这些检查。

2. 选择临时设置或持久化设置

按以下规则处理：

• 临时设置：首次设置、调试和低风险试用时的首选方案
• 持久化设置：仅在用户明确要求每次启动 Claude Code 时都应用代理路径的情况下使用

如需持久化设置，请先确认目标文件，然后将键合并到 ~/.claude/settings.json。不要替换文件内容。

3. 创建 LiteLLM config.yaml

从文章中的流程开始，但提供程序的命名应与 LiteLLM 文档保持一致：

model_list:
  - model_name: claude-opus-4.5
    litellm_params:
      model: github_copilot/claude-opus-4.5
      drop_params: true

说明以下字段：

• model_name：Claude Code 将请求的逻辑名称
• model：LiteLLM 提供程序路由，使用 github_copilot/<model>
• drop_params: true：转发到 Copilot 前移除不受支持的 Anthropic 专用字段

如果用户想使用其他由 Copilot 提供支持的模型，请沿用相同模式：

model_list:
  - model_name: <logical-name>
    litellm_params:
      model: github_copilot/<copilot-model>
      drop_params: true

除非用户已遇到疑似需要覆盖请求头才能解决的拒绝错误，否则默认方案中不要硬编码额外请求头。

4. 安装并启动 LiteLLM

首选安装方式：

uv tool install "litellm[proxy]"

备用方式：

pip install "litellm[proxy]"

从包含 config.yaml 的目录启动代理：

litellm --config config.yaml --port 4000

告诉用户保持该终端打开，因为在验证过程中，日志是最快获取准确信息的途径。

5. 说明 GitHub 设备授权

首次成功向 GitHub Copilot 提供方发送请求时，LiteLLM 可能会启动设备授权流程：

1. LiteLLM 打印验证 URL 和设备代码
2. 用户打开 URL 并批准请求
3. LiteLLM 在本地存储生成的凭据，以供后续使用

也可以覆盖令牌位置：

• GITHUB_COPILOT_TOKEN_DIR
• GITHUB_COPILOT_ACCESS_TOKEN_FILE

只有当用户需要自定义令牌存储位置、共享环境，或排查凭据过期或放错位置的问题时，才提及这些选项。

6. 配置 Claude Code

临时用于 PowerShell 会话：

$env:ANTHROPIC_AUTH_TOKEN = "sk-any-string"
$env:ANTHROPIC_BASE_URL = "http://localhost:4000"
$env:ANTHROPIC_MODEL = "claude-opus-4.5"
$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"
claude

临时用于 Bash 或 Zsh 会话：

export ANTHROPIC_AUTH_TOKEN="sk-any-string"
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_MODEL="claude-opus-4.5"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
claude

如需持久配置，将这些键合并到 ~/.claude/settings.json：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-any-string",
    "ANTHROPIC_BASE_URL": "http://localhost:4000",
    "ANTHROPIC_MODEL": "claude-opus-4.5",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

安全合并行为：

• 如果文件不存在，则创建文件
• 如果文件存在，则保留所有无关的顶层键
• 保留与此工作流无关的现有 env 条目
• 仅更新上述四个键
• 如果 JSON 格式错误，则停止并报告解析问题，而不要覆盖文件

7. 验证请求链路

尽可能使用两个终端：

• 终端 A 运行 LiteLLM
• 终端 B 运行 claude

让用户提出一个简短的请求，例如编写一个简短脚本或进行代码审查，然后验证：

• Claude Code 正常启动
• LiteLLM 日志显示收到入站请求
• LiteLLM 日志显示 GitHub Copilot 模型路由，通常为 github_copilot/<model>

正常的请求路径如下：

Claude Code -> LiteLLM -> GitHub Copilot -> LiteLLM -> Claude Code

8. 故障排查

如果 Claude Code 报告找不到模型、出现类似 404 的故障，或 LiteLLM 提示模型不存在：

• 精确比对 ANTHROPIC_MODEL 和 model_name
• 检查大小写、标点和连字符

如果 LiteLLM 始终没有收到请求：

• 确认 ANTHROPIC_BASE_URL 指向 http://localhost:4000
• 确认 LiteLLM 仍在该端口运行
• 确认环境变量是在启动 claude 的同一个 shell 会话中设置的
• 如果 URL 正确但仍无响应，请检查本地防火墙或端口冲突

如果 LiteLLM 已连接 GitHub Copilot，但收到 401 或 403 响应：

• 重启 LiteLLM 并重试，以重新进行设备授权
• 确认 GitHub 帐户仍有权使用 Copilot
• 如果设置了自定义令牌目录变量，请确认它们指向预期的文件

高级备用方案：覆盖标头

本文使用明确的 Copilot 风格标头。当前 LiteLLM 文档将 GitHub Copilot 列为提供方，并介绍了标头覆盖支持。

只有在以下情况下，才使用明确的 extra_headers：

• 基本提供方流程已连接 Copilot，但仍需要覆盖客户端格式
• 用户已有证据表明，特定环境使用编辑器风格的标头效果更好

备用方案示例：

model_list:
  - model_name: claude-opus-4.5
    litellm_params:
      model: github_copilot/claude-opus-4.5
      drop_params: true
      extra_headers:
        editor-version: "vscode/1.85.1"
        editor-plugin-version: "copilot/1.155.0"
        Copilot-Integration-Id: "vscode-chat"
        user-agent: "GithubCopilot/1.155.0"

将此方案作为高级备用方案介绍，而不是通用默认方案。

输出检查清单

使用此技能回答实际用户请求时，请包含：

• 简短的合规性说明
• 完整的 config.yaml 或需要应用的差异
• 适合相应 shell 的命令
• 说明配置是临时还是持久的
• 验证路径
• 如果出现故障，提供最精简且相关的故障排查部分

安全提示

• 不要声称 GitHub 官方支持此变通方案。
• 不要暗示虚设的 ANTHROPIC_AUTH_TOKEN 是真实的 Copilot 凭据。
• 不要建议整体替换 ~/.claude/settings.json。
• 不要将过时的模型名称说成当前一定可用；如果用户指定了某个模型，请保留 github_copilot/<model> 模式，并说明 Copilot 提供的模型可能会有所变化。