---

为什么选择本地部署？

• 零订阅成本：无需 Claude Pro / API 付费，一次性部署永久使用
• 数据隐私安全：代码、提示词、对话记录完全不出内网
• 毫秒级响应：内网直连，告别公网延迟和限流
• GPU 物尽其用：V100 32GB 不再闲置，成为真正的 AI 编程加速器

---

📋 阅读导航

章节	内容	难度
前置条件	确认 vLLM 服务就绪	⭐
Node.js 环境	安装运行依赖	⭐
Claude Code	CLI 工具安装	⭐
绕过登录	核心破解步骤	⭐⭐
环境变量	指向本地模型	⭐⭐
验证使用	启动并对话测试	⭐
常见问题	排错速查	⭐⭐
进阶路由	兼容性增强方案	⭐⭐⭐

---

系统架构一览

请求链路：Claude Code CLI → HTTP API → vLLM 推理引擎 → Qwen3-35B (AWQ) → NVIDIA V100

---

一、前置条件

在开始之前，请确保你的 vLLM 服务已经正常运行，并且能够通过 HTTP 访问。

1.1 vLLM 启动参数（⚠️ 必须包含以下三项）

核心注意：--enable-auto-tool-choice 和 --tool-call-parser qwen3_coder 必须同时开启，否则 Claude Code 的 Agent 模式（文件编辑、命令执行等）将无法工作。

1.2 接口连通性测试

curl http://192.168.101.12:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3.6-35B-A3B-AWQ",
    "messages": [{"role": "user", "content": "hi"}]
  }'

若返回 "choices": [...] JSON 响应，说明服务就绪 ✅

---

二、安装 Node.js 环境

Claude Code 基于 Node.js 构建，要求 ≥ 18.0。

# 添加 NodeSource 官方仓库
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -

# 安装 Node.js
sudo apt install -y nodejs

# 验证版本
node --version   # v18.x 或更高

---

三、安装 Claude Code

npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version
# 预期输出：v2.1.126 或更高版本

---

四、绕过登录限制（关键）

Claude Code 首次启动强制要求 Anthropic Web 登录。对于纯本地部署，我们需要手动注入最小化配置来跳过这一步。

4.1 清理旧配置（如曾运行过）

rm -rf ~/.claude ~/.claude.json

4.2 创建最小化配置文件

mkdir -p ~/.claude
cat > ~/.claude.json << 'EOF'
{
  "hasCompletedOnboarding": true,
  "apiKey": "dummy",
  "userID": "local-user"
}
EOF

字段	值	作用
hasCompletedOnboarding	true	标记已完成首次引导，跳过登录页
apiKey	dummy	占位值，本地模式不校验
userID	local-user	用户标识，任意字符串均可

---

五、配置环境变量直连 vLLM

这是整套方案最核心的步骤。以下环境变量告诉 Claude Code 将所有模型请求转发到你的本地 vLLM 服务，而非 Anthropic 云端。

5.1 临时生效（当前终端）

export ANTHROPIC_BASE_URL="http://192.168.101.12:8000"
export ANTHROPIC_API_KEY="dummy"
export ANTHROPIC_AUTH_TOKEN="dummy"
export ANTHROPIC_DEFAULT_SONNET_MODEL="Qwen3.6-35B-A3B-AWQ"
export ANTHROPIC_DEFAULT_OPUS_MODEL="Qwen3.6-35B-A3B-AWQ"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="Qwen3.6-35B-A3B-AWQ"

5.2 永久生效（推荐写入 ~/.bashrc）

cat >> ~/.bashrc << 'EOF'

# === Claude Code Local vLLM Config ===
export ANTHROPIC_BASE_URL="http://192.168.101.12:8000"
export ANTHROPIC_API_KEY="dummy"
export ANTHROPIC_AUTH_TOKEN="dummy"
export ANTHROPIC_DEFAULT_SONNET_MODEL="Qwen3.6-35B-A3B-AWQ"
export ANTHROPIC_DEFAULT_OPUS_MODEL="Qwen3.6-35B-A3B-AWQ"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="Qwen3.6-35B-A3B-AWQ"
EOF

source ~/.bashrc

⚠️ 关键提醒

1. ANTHROPIC_BASE_URL 不要加 /v1 后缀，Claude Code 会自动拼接 /v1/messages 路径
2. 三个 ANTHROPIC_DEFAULT_*_MODEL 的值必须与 vLLM 的 --served-model-name 完全一致（区分大小写）
3. API_KEY 和 AUTH_TOKEN 可以是任意非空字符串，本地 vLLM 默认不鉴权

---

六、验证与使用

6.1 启动 Claude Code

claude --model "Qwen3.6-35B-A3B-AWQ"

若仍提示 Not logged in，请返回第四节检查配置文件权限和内容格式。

6.2 预期成功界面

当你看到 Claude> 提示符，即表示已成功连接到本地 Qwen3 模型！

6.3 常用命令速查

命令	功能
/help	查看全部可用指令
/model	查看当前使用的模型名称
/clear	清空当前对话历史
/cost	查看本次会话的 Token 消耗（本地模式下显示为估算值）
exit 或 Ctrl+C	退出会话

6.4 第一个对话测试

Claude> 你好，请用 Python 写一个快速排序算法，要求包含类型注解和单测

如果模型返回格式正确的 Python 代码并附带解释，恭喜你 🎉 —— 你的完全离线 AI 编程助手已就绪！

---

七、常见问题与解决方案

Q1：启动时提示 Not logged in / Please run /login

原因：~/.claude.json 未被正确读取，或之前缓存了云端登录状态。

解决：

# 彻底清理所有配置
rm -rf ~/.claude ~/.claude.json ~/.config/claude

# 重新执行第四节的配置文件创建步骤
mkdir -p ~/.claude
cat > ~/.claude.json << 'EOF'
{
  "hasCompletedOnboarding": true,
  "apiKey": "dummy",
  "userID": "local-user"
}
EOF

---

Q2：报错 API Error: 400 Missing model in request body

原因：Claude Code 发送请求时未携带 model 字段，或 vLLM 侧模型名不匹配。

排查清单：

• vLLM 启动时包含 --served-model-name "Qwen3.6-35B-A3B-AWQ"
• 环境变量 ANTHROPIC_DEFAULT_SONNET_MODEL 与该名称一字不差
• curl 测试能正常返回 JSON
• echo $ANTHROPIC_BASE_URL 输出正确且不含 /v1

---

Q3：请求超时或连接被拒绝

排查：

# 1. 确认环境变量已载入
echo $ANTHROPIC_BASE_URL

# 2. 从本机测试 vLLM 连通性
curl -v http://192.168.101.12:8000/v1/models

# 3. 检查 vLLM 监听地址是否为 0.0.0.0（而非 127.0.0.1）
netstat -tlnp | grep 8000

---

Q4：模型响应速度慢（> 5秒/token）

预期性能：V100 32GB 运行 Qwen3-35B-AWQ， typical 速度约 20~30 tokens/s（取决于输入长度）。若远低于此值，可尝试以下优化：

# 启用 chunked prefill 加速长文本处理
--enable-chunked-prefill

# 适当降低最大上下文长度，减少 KV Cache 占用
--max-model-len 16384

# 提高 GPU 显存利用率（留足余量防止 OOM）
--gpu-memory-utilization 0.90

# 使用更小的模型对比测试（如 Qwen2.5-7B-Coder）

---

Q5：Tool Use（文件编辑 / Bash 命令）不工作

原因：vLLM 未开启工具调用解析，或模型不支持 function calling。

解决：

1. 确认 vLLM 启动参数包含：

--enable-auto-tool-choice \
--tool-call-parser qwen3_coder

2. 确认使用的是 Qwen3 系列模型（原生支持 function calling）。

3. 在 Claude Code 内用 /tools 查看可用工具列表是否加载成功。

---

八、进阶：使用 claude-code-router 增强兼容性

如果你的 vLLM 版本较旧，或返回的消息格式与 Claude Code 的期望不完全一致，可以通过 claude-code-router（ccr） 作为中间适配层进行格式转换。

8.1 安装 ccr

npm install -g @musistudio/claude-code-router

8.2 创建路由配置

mkdir -p ~/.claude-code-router
cat > ~/.claude-code-router/config.json << 'EOF'
{
  "PORT": 3456,
  "Providers": [
    {
      "name": "my-vllm",
      "api_base_url": "http://192.168.101.12:8000/v1/chat/completions",
      "api_key": "dummy",
      "model_name": "Qwen3.6-35B-A3B-AWQ",
      "override_model": "Qwen3.6-35B-A3B-AWQ"
    }
  ],
  "Router": {
    "default_provider": "my-vllm"
  }
}
EOF

8.3 双终端启动

终端 A — 启动路由服务：

ccr start --foreground
# 预期输出：Listening on port 3456...

终端 B — 指向 ccr 启动 Claude Code：

export ANTHROPIC_BASE_URL="http://localhost:3456"
export ANTHROPIC_API_KEY="dummy"
claude --model "Qwen3.6-35B-A3B-AWQ"

此时 Claude Code → ccr → vLLM 的三层链路建立完成，ccr 会自动处理消息格式适配、错误重试和流式响应转换。

---

完整部署流程回顾

---

写在最后

通过以上 8 个步骤，你已经成功将 Claude Code 从「云端付费服务」转变为「完全自主可控的本地 AI 编程助手」。

现在你可以：

• 🖥️ 在终端中与 AI 进行实时代码对话
• 📝 让 AI 协助编写、重构、审查代码
• 🐛 直接让 AI 读取错误日志并给出修复建议
• 🔒 全程离线运行，敏感代码绝不出内网

如果你在实际部署中遇到本文未覆盖的异常，欢迎在评论区留言交流。看到都会回复！

---

参考资料

• Claude Code 官方文档
• vLLM 官方文档
• Qwen3 GitHub 仓库
• claude-code-router GitHub

---

原创技术文章 · 转载请标明出处