Claude Code 私有化部署完整教程 - 本地大模型、内网、合规
Claude Code 能私有化部署吗？本文详解 Claude Code 配置本地大模型、跳过认证、企业内网部署、私有化方案完整教程。
ClaudeCode 私有化部署 是企业用户最关心的话题之一。ClaudeCode 可以用私有化大模型吗、ClaudeCode 配置本地大模型 怎么搞、ClaudeCode 配置本地大模型 跳过认证 的步骤是什么、ClaudeCode 接入 Ollama 本地模型 实际能用到什么程度——这些问题本文一次讲清。
先把结论摆出来：Claude Code 客户端本身就是本地运行的命令行工具，但默认连接 Anthropic 云端模型。要做完整意义上的私有化，需要把模型也换成本地或私有部署的版本。整个过程涉及客户端配置、协议兼容层、本地推理引擎、工具调用兼容性四个方面。
Claude Code 能私有化部署吗
Claude Code 私有化大模型 方案能跑通，但要分清”私有化”的两层含义。
| 私有化层级 | 含义 | 实现难度 |
|---|---|---|
| 客户端本地化 | Claude Code 程序跑在本地机器 | 默认就是 |
| 数据不出本机 | 提示词 / 代码不上传 Anthropic | 需要换本地模型 |
| 完全离线 | 断网也能用 | 需要本地模型 + 本地依赖 |
| 企业内网部署 | 整个组织共享私有模型服务 | 网关 + 鉴权 |
只有第二层及以上才是”真正意义上的私有化部署”。客户端本身已经在本地（开源代码 + 本地二进制），关键在模型端。
私有化部署的两种含义
含义一：客户端本地运行（默认已是）
Claude Code 是 Anthropic 官方发布的 CLI 工具，安装后跑在你自己的电脑或服务器上：
# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash
# 或者 npm
npm install -g @anthropic-ai/claude-code
启动 claude 之后，整个交互界面、文件读写、shell 执行都在本地。但每次问问题时，提示词 + 上下文会发到 Anthropic 服务器——这一步是隐私敏感场景里不可接受的。
含义二：模型也跑在本地（真正的私有化）
把模型推理也搬到本地或者私有服务器。这就是 Claude Code 私有化大模型 的核心：
用户输入
↓
Claude Code 客户端（本地）
↓
私有推理服务（本地 Ollama / 内网 vLLM / 自建 LiteLLM Gateway）
↓
本地 GPU / CPU 计算
↓
返回结果（数据全程不出私有网络）
为什么企业需要私有化
| 动机 | 说明 |
|---|---|
| 数据合规 | 金融 / 医疗 / 政企 / 国资有数据出境限制 |
| 代码安全 | 商业代码、IP 不能上传第三方 |
| 网络隔离 | 内网环境完全不通公网 |
| 成本可控 | 大用量场景本地推理比 API 更便宜 |
| 定制能力 | 私有 fine-tune 模型集成 |
| 延迟敏感 | 本地推理省网络往返 |
中大型企业里，数据合规 + 内网隔离是头两位的硬性约束。哪怕本地模型能力略弱，也比”不能用”强。
Claude Code 接入本地模型完整流程
Claude Code 接入本地模型 标准流程四步：
第一步：装 Ollama（或其他本地推理引擎）
# macOS / Linux 一行装
curl -fsSL https://ollama.com/install.sh | sh
# Windows 去 ollama.com 下安装包
# 验证
ollama --version
第二步：拉一个支持工具调用的模型
Claude Code 接入本地模型 的关键不在客户端，而在模型必须 支持 function calling / tool use。否则你在 Claude Code 里让它创建文件、运行命令，它只会输出一段普通文本不会真的调工具。
推荐选项：
| 模型 | 大小 | 工具调用 | 编程能力 |
|---|---|---|---|
| Qwen 2.5 Coder 14B / 32B | 中-大 | 良好 | 优秀（国内） |
| DeepSeek-Coder V3 | 大 | 良好 | 顶级（开源） |
| Llama 3.1 70B | 大 | 优秀 | 优秀 |
| CodeLlama 34B | 大 | 中等 | 良好 |
拉取示例：
ollama pull qwen2.5-coder:14b
# 或者更大的
ollama pull qwen2.5-coder:32b
第三步：跑 LiteLLM 网关做协议转换
Ollama 自带 OpenAI 兼容 API，但 Claude Code 走 Anthropic 协议，中间要做一层翻译。LiteLLM 是社区里最常用的方案：
pip install litellm
写一个 litellm_config.yaml：
model_list:
- model_name: claude-3-5-sonnet-20241022
litellm_params:
model: ollama/qwen2.5-coder:14b
api_base: http://localhost:11434
litellm_settings:
drop_params: True
启动：
litellm --config litellm_config.yaml --port 4000
第四步：配置 Claude Code 指向本地
编辑 ~/.claude/settings.json（Windows 在 %USERPROFILE%\.claude\settings.json）：
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:4000",
"ANTHROPIC_API_KEY": "sk-fake-anything-works"
}
}
启动 claude 验证：
> 你是谁？
如果回答带 Qwen / DeepSeek 风格，说明已经接到本地模型，整个对话不再走 Anthropic 云端。
跳过 Anthropic 认证完整步骤
ClaudeCode 配置本地大模型 跳过认证 是私有化场景最常见的需求。Anthropic 的认证机制基于 API key，但本地端点不需要真实 key——只要客户端格式上能 pass，发出去的 key 在本地服务被忽略。
完整跳过步骤：
1. 设置一个假 key（任意字符串）
# Linux / macOS
export ANTHROPIC_API_KEY="sk-local-fake-key-12345"
# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-local-fake-key-12345"
2. 把 base URL 指向本地网关
export ANTHROPIC_BASE_URL="http://localhost:4000"
3. 启动 Claude Code 时绕过初始登录流程
如果 Claude Code 还要走 OAuth 登录，settings.json 里：
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:4000",
"ANTHROPIC_API_KEY": "sk-local-fake-key-12345"
}
}
通常这样就够了。具体跳过 OAuth 的方式可能随 Claude Code 版本调整，以最新版命令行参数为准。
4. 验证
claude --version
claude
进入交互后看是否能直接对话，不弹登录。
推荐的本地大模型清单
ClaudeCode 本地大模型 选型决定了私有化方案的可用程度。按编程能力 / 工具调用 / 硬件需求三维度排：
个人开发者（消费级 GPU / Mac Apple Silicon）
| 模型 | 显存需求（4-bit 量化） | 编程能力 | 备注 |
|---|---|---|---|
| Qwen 2.5 Coder 7B | 5-6 GB | 中等 | 入门勉强 |
| Qwen 2.5 Coder 14B | 9-10 GB | 良好 | 性价比首选 |
| DeepSeek-Coder V2 16B | 10-12 GB | 优秀 | 强烈推荐 |
工作站 / 单卡 A100 / 多卡消费级
| 模型 | 显存需求 | 编程能力 |
|---|---|---|
| Qwen 2.5 Coder 32B | 20-24 GB | 优秀 |
| Llama 3.1 70B（量化） | 40+ GB | 优秀 |
| DeepSeek-Coder V3 | 大量 | 顶级 |
企业级 / 多卡服务器
跑 70B+ 模型，建议改用 vLLM 而不是 Ollama：
pip install vllm
vllm serve Qwen/Qwen2.5-Coder-32B-Instruct --port 8000
vLLM 吞吐量比 Ollama 高很多，适合多用户并发。
接入本地模型常见问题
ClaudeCode 接入本地模型无法创建文件
最常见问题。Claude Code 接入本地模型 后，Claude 回答了一段”我已经创建了文件”，但实际文件没出现，或者反过来明明该写文件的它只输出纯文本。
| 原因 | 排查方式 | 解决 |
|---|---|---|
| 模型不支持工具调用 | 看模型 model card 是否有 “function calling” | 换支持工具的模型 |
| 模型参数量太小 | 7B 以下容易瞎调 | 升到 14B+ |
| LiteLLM 转换层 bug | 看 LiteLLM 日志的工具调用 JSON | 升级 LiteLLM |
| Ollama 版本旧 | ollama --version | 升到最新 |
| 提示词触发不对 | Claude Code 的系统提示词 | 一般无需改 |
排查命令：
# 查看 LiteLLM 日志（启动时不要 daemon 化）
litellm --config litellm_config.yaml --port 4000 --detailed_debug
看看请求里有没有正确的 tools 字段，模型返回有没有 tool_calls。
上下文不够
本地模型的上下文窗口通常远小于 Claude 官方（Claude 是几十万 token 级，本地 14B 模型常见 32K / 128K）。大型代码库一次性扔进去会爆。
解决：
- 选上下文窗口大的模型（Qwen 2.5 系列可达 128K）
- 用 Claude Code 内置的文件分块策略
- 显式精简上下文
速度太慢
本地推理速度受限于 GPU。14B 模型在 RTX 4090 上大约 30-50 token/s，比 Anthropic 云端的几百 token/s 慢一截。
提速思路：
- 用量化版（4-bit / 8-bit）
- 换 vLLM 替代 Ollama
- 升 GPU
- 接受现状（私有化的代价之一）
企业内网部署架构
完整的企业私有化部署架构如下：
开发者机器（多台）
│
├── Claude Code 客户端
│ └─ ANTHROPIC_BASE_URL = http://gateway.corp.internal
│
▼
内网网关（LiteLLM Gateway 集群）
│
├── 鉴权（公司 SSO / API key 管理）
├── 路由（按用户 / 按任务路由到不同模型）
├── 计费 / 审计日志
│
▼
推理后端集群（vLLM + GPU 节点）
│
└─ 多模型并行：通用模型 + 编程模型 + 企业 fine-tune 模型
关键组件：
| 组件 | 推荐方案 |
|---|---|
| 客户端 | Claude Code 官方 CLI |
| 协议网关 | LiteLLM Gateway（开源） |
| 推理引擎 | vLLM / TGI / SGLang |
| 鉴权 | 公司 SSO + LiteLLM virtual key |
| 模型权重 | 内网 S3 / MinIO |
| 日志审计 | ELK / Loki + Prometheus |
LiteLLM Gateway 的一个亮点：可以把不同模型映射成同一个”虚拟”的 Anthropic 模型名，对客户端完全透明。底层换 GPU、换权重都不影响开发者。
Claude Code Max / Pro 多设备使用
ClaudeCodeMax 最多支持几个设备 这个问题，截至本文撰写时，Anthropic 的订阅档（Pro / Max / Team）按账号计费而不是按设备数硬性限制，但有以下注意：
| 订阅档 | 多设备 | 备注 |
|---|---|---|
| Free | 单账号可登录多设备 | 共享配额 |
| Pro | 多设备共享配额 | 同账号，正常使用 |
| Max | 多设备共享更高配额 | 同账号 |
| Team | 团队成员各自账号 | 按席位计费 |
| Enterprise | 组织级 | 自定义 |
关键点：
- 同账号同时在 N 台机器登录 Claude Code 通常允许，但配额是共享的
- 频繁切换设备可能触发反滥用检查
- 团队场景建议买 Team 档每人独立席位，比共享一个 Pro 更稳
具体限制以 Anthropic 官方订阅条款为准，本文不写死数字。
私有化部署的局限性
诚实讲，ClaudeCode 私有化部署 不是免费午餐：
| 局限 | 影响 | 缓解 |
|---|---|---|
| 本地模型 < 云端 Claude | 复杂任务能力差距明显 | 关键任务走云端 + 脱敏 |
| 硬件成本 | 单卡数千到数万 | 共享集群摊薄 |
| 维护成本 | 网关 / 推理 / 模型更新 | 用成熟方案如 LiteLLM |
| 工具调用稳定性 | 不如云端原生 | 选大模型 + 多测 |
| 升级滞后 | 本地版本落后官方 | 定期跟进 |
最务实的方式是混合部署：敏感代码走本地模型，通用调研走云端 API，给开发者两套 profile 让他自己切。
实测：本地模型 + Claude Code 编程任务表现
主观对照（仅参考，硬件 RTX 4090 + 14B / 32B 模型）：
| 任务类型 | Claude Opus（云） | Qwen 2.5 Coder 32B（本地） | 差距 |
|---|---|---|---|
| 单文件 bug 修复 | 优秀 | 良好 | 小 |
| 添加新功能 | 优秀 | 良好 | 小 |
| 跨文件重构 | 优秀 | 中等 | 中 |
| 复杂调试 | 顶级 | 中等 | 较大 |
| 架构设计 | 顶级 | 一般 | 大 |
| 中文沟通 | 优秀 | 优秀 | 无 |
结论：日常开发 70-80% 的任务本地模型够用，剩下 20-30% 复杂任务还是云端能力领先。
FAQ
私有化部署 ClaudeCode 要联网吗？
不需要外网，但需要内网联通客户端到推理服务。如果整个流程都在本机（Claude Code + LiteLLM + Ollama 都在同一台机器），完全断网也能跑。
企业要不要走 Bedrock？
如果你的合规要求是 “不能给第三方”，Bedrock（AWS）本质上还是给 Anthropic 的合作云厂商，部分场景可能不满足。但 Bedrock 的优势：
- AWS 数据保留 + 加密合规一套齐
- 不需要自己采购 GPU
- 价格按 token 算，无固定成本
合规要求 “数据不出 AWS” 的话 Bedrock 是好选择，要求 “数据不出本组织” 的话还得自建私有化。
个人开发者值得搞私有化吗？
多数情况下不值得。理由：
- 硬件投入数千到数万
- 维护时间成本
- 本地模型能力不如云端
- API 调用按量付费，个人用量月几十美元搞定
除非你：
- 真的不能联网（保密环境）
- 数据敏感到不能上云
- 大量重复推理（>>$100/月）
否则老老实实用 Claude API 更划算。
私有化用 Bedrock 还是自建？
| 维度 | Bedrock | 自建 |
|---|---|---|
| 数据控制 | 部分 | 完全 |
| 模型能力 | Anthropic 原版 | 开源模型 |
| 成本 | 按量付费 | 硬件 + 运维固定成本 |
| 上手难度 | 低 | 中-高 |
| 适合规模 | 中小到大 | 大型 |
中型企业可以混合：日常 Bedrock + 涉密项目自建。
私有化能跟 Claude 官方功能完全对齐吗？
不能完全对齐。Anthropic 官方的一些功能（artifacts、MCP 高级特性、Computer Use 等）依赖云端服务，本地模型短期内追不上。私有化方案是”能力 / 私密性”的权衡，不是替代品。
小结
Claude Code 私有化部署 的核心路径：
- Claude Code 客户端 → 本地或内网安装
- LiteLLM 做协议转换网关
- Ollama / vLLM 跑本地大模型（Qwen 2.5 Coder / DeepSeek-Coder V3 推荐）
- 配置
ANTHROPIC_BASE_URL+ 假 API key 跳过认证 - 企业场景加 SSO + 审计 + GPU 集群
私有化不是简单的”换 base URL”，背后是模型选型、协议兼容、工具调用、硬件、运维的整套工程。但只要把每一步走完，ClaudeCode 配置本地大模型 就能真正做到代码、提示词、上下文完全不出内网。