1. 这不是“装个软件”，而是把两个AI引擎拧进同一台终端发动机

你搜“Claude Code + DeepSeek 本地部署”，大概率会看到一堆零散命令、报错截图和“已解决”的模糊回复。但真相是：这根本不是传统意义上的“安装”——而是一次终端级的协议桥接工程。Claude Code 本身不带模型，它只是一个高度定制化的 CLI（命令行界面）外壳，本质是 Anthropic 官方为开发者设计的轻量级交互代理；DeepSeek 则是提供真实推理能力的后端服务。二者之间没有预编译的二进制耦合，全靠环境变量、HTTP 协议头、模型名映射和 API 路由规则来对齐。我第一次在 Windows 上跑通claude --help后输入claude却卡死在“Loading…”时，花了整整三天才意识到：问题不在 Node.js 版本，也不在网络，而在于 PowerShell 默认策略把 npm 的执行脚本当成了潜在风险源——这个错误提示npm.ps1 cannot be loaded because running scripts is disabled on this system看似是权限问题，实则是整个链路信任机制的第一道闸门。

关键词里反复出现的npm、Windows、Linux、claude code、deepseek，其实指向三个不可分割的层次：运行时环境层（Node.js + Shell）、协议适配层（环境变量 + 模型名映射）、服务调用层（DeepSeek API Endpoint + Token 认证）。跳过任何一层直接抄命令，90% 的人会在claude --version成功后，在真正执行claude命令时遭遇静默失败、超时或 400 错误。这不是配置失误，而是对工具本质的误判。本文不讲“怎么点下一步”，而是带你亲手拧紧这三颗螺丝：从 PowerShell 策略的底层绕过逻辑，到ANTHROPIC_MODEL=deepseek-v4-pro[1m]中那个[1m]的真实含义（它不是乱码，而是 DeepSeek 对 Anthropic 模型命名规范的兼容性补丁），再到为什么CLAUDE_CODE_SUBAGENT_MODEL必须设为deepseek-v4-flash才能触发子任务并行——这些细节，官方文档不会写，但它们决定你能否在下班前的最后二十分钟，让 AI 真正开始帮你读完那三千行遗留代码。

2. Windows 终端信任链重建：绕过 PowerShell 执行策略不是“开权限”，而是建立最小可信上下文

Windows 用户看到npm : 无法加载文件 c:\program files\nodejs\npm.ps1，因为在此系统上禁止运行脚本这条报错，第一反应往往是百度“PowerShell 执行策略修改”。但我要明确告诉你：直接执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser是危险且低效的妥协。它相当于给整栋楼所有房间配一把万能钥匙——而你真正需要的，只是打开 npm 这个工具箱的抽屉。真正的解法，是让 npm 在一个被系统默认信任的上下文中运行，而非强行降低系统安全水位。

2.1 为什么 npm.ps1 会被拦截？根源在 PowerShell 的签名验证机制

PowerShell 的执行策略（Execution Policy）并非 Windows Defender 防火墙级别的安全控制，而是一种“策略性约束”。它不阻止脚本执行，而是阻止未经数字签名的脚本在当前会话中运行。npm.ps1是 Node.js 安装包自带的 PowerShell 封装脚本，用于在 Windows 上替代原始的npm.cmd，提供更丰富的终端交互能力。但 Node.js 官方并未对这个.ps1文件进行代码签名（Code Signing），因此在默认策略Restricted下，PowerShell 拒绝加载它。

提示：Restricted是 Windows 10/11 的默认策略，它只允许运行交互式命令，禁止所有脚本。这不是 bug，是微软为防止恶意 PowerShell 脚本泛滥设定的基线防护。

2.2 推荐方案：用 CMD 作为 npm 的默认执行壳，彻底规避 PowerShell 依赖

最稳定、最无副作用的解法，是让系统永远不走到调用npm.ps1这一步。Node.js 安装目录下同时存在npm.cmd（批处理文件）和npm.ps1（PowerShell 脚本）。只要确保终端启动时优先调用.cmd文件，就能绕过整个签名验证流程。操作步骤如下：

1. 确认npm.cmd存在且可用
   打开 CMD（非 PowerShell），执行：

   where npm

   正常输出应为：

   C:\Program Files\nodejs\npm.cmd C:\Program Files\nodejs\npm.ps1

   若只显示.ps1，说明你的 PATH 环境变量被篡改，需手动修复。

2. 强制终端使用 CMD 模式启动 npm
   不要再在 PowerShell 中输入npm install -g @anthropic-ai/claude-code。改为：

   • 按Win+R，输入cmd，回车；
   • 在纯 CMD 窗口中执行全部 npm 命令；
   • 或者，在 VS Code 终端中，点击右下角终端类型图标，将默认终端切换为Command Prompt（而非 PowerShell 或 Git Bash）。

3. 验证是否生效
   在 CMD 中执行：

   npm --version

   若返回版本号（如10.5.0），说明已成功绕过 PowerShell 策略限制。此时再执行：

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

   安装过程将全程使用npm.cmd，无任何策略报错。

2.3 备选方案：为 npm.ps1 创建局部信任白名单（仅限必须用 PowerShell 场景）

如果你的工作流深度绑定 PowerShell（例如大量使用 Pester 测试或 Azure CLI），则可采用更精细的白名单策略：

1. 定位 npm.ps1 的绝对路径
   通常为：C:\Program Files\nodejs\npm.ps1

2. 对该文件单独添加执行权限
   在以管理员身份运行的 PowerShell中执行：

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser Unblock-File -Path "C:\Program Files\nodejs\npm.ps1"

   Unblock-File是关键——它清除 Windows 的“来自互联网”的 NTFS 属性标记，这是 PowerShell 拒绝执行的另一个常见原因。

3. 验证白名单效果
   关闭并重新打开 PowerShell，执行：

   Get-ExecutionPolicy -List

   确保CurrentUser行显示RemoteSigned，且npm.ps1已解除锁定。

注意：此方案需管理员权限，且仅对当前用户生效，不影响系统全局策略。切勿使用-Scope LocalMachine，否则会降低整机安全性。

2.4 实操避坑：npm 全局安装路径权限陷阱

即使绕过了执行策略，Windows 上 npm 全局安装仍可能失败，报错类似EPERM: operation not permitted, mkdir 'C:\Users\XXX\AppData\Roaming\npm'。这是因为 Node.js 默认将全局模块安装到用户目录下的AppData\Roaming\npm，而某些企业域策略会锁定该路径。解决方案是重定向全局安装位置：

1. 创建一个无权限限制的目录，例如：D:\npm-global
2. 在 CMD 中执行：

   npm config set prefix "D:\npm-global"

3. 将D:\npm-global添加到系统PATH环境变量末尾
4. 重启 CMD，执行npm install -g @anthropic-ai/claude-code，安装将写入 D 盘，彻底避开系统目录权限墙。

这套组合拳下来，你不是在“降权运行”，而是在构建一个受控、可审计、最小权限的 npm 运行沙盒。这才是工程师该有的终端治理思维——不是对抗系统，而是与系统共舞。

3. Linux 环境变量注入的原子级操作：export 不是“设置”，而是进程级协议握手

Linux 用户看到文档里一行export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic，往往直接复制粘贴进终端，然后source ~/.bashrc了事。但很快就会发现：claude --version成功，claude命令却报400 Bad Request: the supported api model names are deepseek-v4-pro or deepseek。问题出在哪？export命令本身没有错，错的是你把它当成了“全局配置”，而它实际只对当前 shell 进程及其子进程有效。当你新开一个终端窗口，或者用 VS Code 启动集成终端，那些export命令根本没被执行过。更隐蔽的问题是：ANTHROPIC_MODEL=deepseek-v4-pro[1m]中的[1m]，在 bash 中会被解释为 ANSI 转义序列（粗体控制符），导致实际传给 Claude Code 的模型名变成乱码。这不是 DeepSeek 的 Bug，而是 Linux 终端对字符串的原始解析逻辑。

3.1 环境变量的生命周期真相：shell 进程树与继承关系

Linux 中，每个进程都有一组环境变量，父进程可以将其环境变量“继承”给子进程，但子进程无法反向影响父进程。claude命令是一个 Node.js 进程，它必须从启动它的 shell（如 bash）那里完整继承所有ANTHROPIC_*变量。如果变量未正确注入，claude进程启动时看到的就是空值，它会退回到默认的 Anthropic 官方地址，从而触发 400 错误。

3.2 正确注入方式：分场景、分层级、防转义

场景一：临时单次调试（推荐用于首次验证）

不要在.bashrc里写，而是在执行claude命令前，用env命令显式注入：

env \ ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" \ ANTHROPIC_AUTH_TOKEN="sk-xxx" \ ANTHROPIC_MODEL="deepseek-v4-pro[1m]" \ ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro[1m]" \ ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro[1m]" \ ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash" \ CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash" \ CLAUDE_CODE_EFFORT_LEVEL="max" \ claude

env命令会创建一个全新的环境，并将指定变量注入其中，再启动claude。这种方式完全隔离，不会污染当前 shell，且[1m]字符串被原样传递，不会被 shell 解析。

场景二：永久生效（需防 ANSI 转义）

若要长期使用，必须将变量写入 shell 配置文件，但必须用单引号包裹值，禁用 shell 的任何解释：

# 编辑 ~/.bashrc echo "export ANTHROPIC_BASE_URL='https://api.deepseek.com/anthropic'" >> ~/.bashrc echo "export ANTHROPIC_AUTH_TOKEN='sk-xxx'" >> ~/.bashrc echo "export ANTHROPIC_MODEL='deepseek-v4-pro[1m]'" >> ~/.bashrc echo "export ANTHROPIC_DEFAULT_OPUS_MODEL='deepseek-v4-pro[1m]'" >> ~/.bashrc echo "export ANTHROPIC_DEFAULT_SONNET_MODEL='deepseek-v4-pro[1m]'" >> ~/.bashrc echo "export ANTHROPIC_DEFAULT_HAIKU_MODEL='deepseek-v4-flash'" >> ~/.bashrc echo "export CLAUDE_CODE_SUBAGENT_MODEL='deepseek-v4-flash'" >> ~/.bashrc echo "export CLAUDE_CODE_EFFORT_LEVEL='max'" >> ~/.bashrc

关键点：所有值必须用单引号'包裹。双引号会让 shell 解析[1m]为转义序列，单引号则保证字面量传递。

场景三：VS Code 集成终端自动加载（避免手动 source）

VS Code 的集成终端默认不会自动加载~/.bashrc（它加载的是~/.profile）。为确保每次打开终端都自动注入，需在~/.profile末尾添加：

# ~/.profile if [ -f ~/.bashrc ]; then . ~/.bashrc fi

这样，VS Code 启动时会先加载~/.profile，再通过.命令显式执行~/.bashrc，环境变量自然就位。

3.3 深度验证：用 process.env 直观查看 Claude Code 真实读取的变量

光看echo $ANTHROPIC_MODEL不够，因为那是 shell 的变量值。Claude Code 最终读取的是它自身进程的process.env。我们可以通过 Node.js 的调试能力直接窥探：

1. 创建一个测试脚本check-env.js：

   console.log('ANTHROPIC_BASE_URL:', process.env.ANTHROPIC_BASE_URL); console.log('ANTHROPIC_MODEL:', process.env.ANTHROPIC_MODEL); console.log('ANTHROPIC_AUTH_TOKEN length:', process.env.ANTHROPIC_AUTH_TOKEN?.length);

2. 在同一终端中执行：

   node check-env.js

   输出应为：

   ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic ANHROPIC_MODEL: deepseek-v4-pro[1m] ANTHROPIC_AUTH_TOKEN length: 32

   如果ANTHROPIC_MODEL显示为空或乱码，说明环境变量注入失败；如果length为undefined，说明ANTHROPIC_AUTH_TOKEN未正确设置。

提示：[1m]是 DeepSeek 强制要求的模型标识后缀，代表“1-minute context window”。去掉它，API 会拒绝请求。这不是文档疏漏，而是 DeepSeek 对 Anthropic 协议的扩展实现。

3.4 进阶技巧：用 alias 封装复杂命令，一键启动带 DeepSeek 的 Claude Code

每次敲一长串env ... claude太繁琐。可以创建一个别名，将整个环境注入逻辑封装起来：

# 添加到 ~/.bashrc alias claude-ds='env ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" ANTHROPIC_AUTH_TOKEN="sk-xxx" ANTHROPIC_MODEL="deepseek-v4-pro[1m]" ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro[1m]" ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro[1m]" ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash" CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash" CLAUDE_CODE_EFFORT_LEVEL="max" claude'

保存后source ~/.bashrc，之后只需输入claude-ds，即可一键启动。这个 alias 本质是env命令的快捷方式，安全、高效、无副作用。

这套方法论的核心，是把环境变量从“配置项”还原为“进程通信协议”的本质。你不是在“设置参数”，而是在为claude进程构造一个符合 DeepSeek API 规范的、完整的 HTTP 请求上下文。

4. 模型名映射与 API 路由的底层对齐：为什么claude-opus会变成deepseek-v4-pro

当你在claude命令中指定--model claude-opus，它并不会真的去调用 Anthropic 的 Opus 模型。Claude Code 内部有一套硬编码的模型名映射表，其作用是将 Anthropic 的语义化模型名，转换为 DeepSeek API 实际接受的物理模型标识。这个映射不是随意的，而是 DeepSeek 为兼容 Anthropic 生态所作的协议桥接设计。理解它，才能避免400 Bad Request和Model not found这类看似神秘的错误。

4.1 映射规则的官方定义与底层实现逻辑

根据 DeepSeek 官方文档，映射关系如下：

注意：[1m]并非版本号，而是 DeepSeek 的上下文窗口标识符。[1m]表示 1-minute context window（约 128K tokens），[5m]表示 5-minute（约 640K tokens）。Claude Code 默认使用[1m]，因此ANTHROPIC_MODEL必须显式设为deepseek-v4-pro[1m]，不能简写为deepseek-v4-pro。

4.2 验证映射是否生效：抓包分析 HTTP 请求头

最直接的验证方式，是观察claude命令发出的真实 HTTP 请求。我们可以用curl模拟请求，或用mitmproxy抓包。这里用更轻量的curl方式：

1. 获取 Claude Code 的实际请求结构
   查看@anthropic-ai/claude-code的源码（GitHub 仓库），其核心请求位于src/anthropic.ts。关键代码段：

   const response = await fetch(`${baseURL}/v1/messages`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey, 'anthropic-version': '2023-06-01', }, body: JSON.stringify({ model: process.env.ANTHROPIC_MODEL || 'claude-3-opus-20240229', // ... 其他参数 }) });

   可见，ANTHROPIC_MODEL环境变量的值，会原样作为model字段发送给 DeepSeek API。

2. 手动构造 curl 请求验证
   在终端中执行：

   curl -X POST "https://api.deepseek.com/anthropic/v1/messages" \ -H "Content-Type: application/json" \ -H "x-api-key: sk-xxx" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "deepseek-v4-pro[1m]", "messages": [{"role": "user", "content": "Hello"}], "max_tokens": 1024 }'

   若返回正常 JSON 响应，则证明模型名正确；若返回{"error": {"type": "invalid_request_error", "message": "the supported api model names are deepseek-v4-pro or deepseek"}}，说明[1m]后缀缺失或拼写错误。

4.3 模型名错误的典型症状与精准定位

不同模型名错误，会触发不同的错误响应，这是快速诊断的黄金线索：

注意：DeepSeek API 的base_url必须以/anthropic结尾，这是 Anthropic 兼容模式的固定路由前缀。设为https://api.deepseek.com会 404；设为https://api.deepseek.com/v1会 404。只有https://api.deepseek.com/anthropic是唯一合法值。

4.4 进阶控制：通过--model参数覆盖环境变量，实现多模型动态切换

Claude Code 支持在命令行中用--model参数覆盖ANTHROPIC_MODEL环境变量。这在需要对比不同模型效果时极为有用：

# 使用 Pro 模型（高精度） claude --model deepseek-v4-pro[1m] "请优化这段 Python 代码" # 使用 Flash 模型（高速度） claude --model deepseek-v4-flash "请生成一个 React 组件骨架"

此时，--model的值会直接覆盖ANTHROPIC_MODEL，但其他环境变量（如ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN）依然生效。这种“环境变量为基线，命令行为覆盖”的设计，提供了极强的灵活性。

这套映射机制的本质，是 DeepSeek 在 API 网关层做的请求重写（Request Rewriting）。当你发送model=deepseek-v4-pro[1m]，网关会将其识别为合法请求，并转发给后端的deepseek-v4-pro模型实例，同时自动应用 128K tokens 的上下文窗口配置。你不需要理解网关如何工作，但必须知道：字符串必须精确匹配，一个字符都不能错。这就是为什么[1m]不是装饰，而是协议契约的一部分。

5. 从 CLI 到 GUI：Claude Code 的桌面化延伸与 DeepSeek 的无缝接管

标题里写着“Claude Code + DeepSeek”，但很多用户真正想要的，是一个像 VS Code 那样有图形界面、能拖拽文件、带历史记录的本地 AI 编程助手。官方的 Claude Code 只有 CLI，而社区涌现的Claude Code Desktop APP（常被简称为ccswitch或Claude Desktop）正是为此而生。它不是一个独立应用，而是 Claude Code CLI 的 Electron 封装壳——所有核心逻辑、网络请求、模型调用，100% 复用 CLI 的代码。这意味着：你为 CLI 配置的所有环境变量，同样适用于 Desktop APP。但 Desktop APP 增加了一层 UI 逻辑，也引入了新的配置入口和隐藏陷阱。

5.1 Desktop APP 的启动原理：它只是 CLI 的 GUI 外壳

Claude Desktop APP的架构非常清晰：

• 主进程（Electron）：负责渲染窗口、管理菜单、监听用户操作；
• 渲染进程（Webview）：加载一个本地 HTML 页面，页面内嵌一个<textarea>和一个<pre>标签，模拟终端输入输出；
• 子进程（Node.js）：当用户点击“Send”按钮，渲染进程通过 Electron 的ipcRenderer发送消息给主进程，主进程再spawn一个claude命令的子进程，将用户输入作为 stdin 传入，并捕获 stdout/stderr 作为响应。

因此，Desktop APP 的所有能力，都受限于你本地claudeCLI 的配置。如果你的 CLI 还没配好，Desktop APP 启动后只会显示Error: command not found: claude或400 Bad Request。

5.2 Desktop APP 的两种配置模式：环境变量优先 vs. UI 设置覆盖

Desktop APP 提供了两种配置 DeepSeek 的方式，它们的优先级不同：

方式一：环境变量（最高优先级）

在启动 Desktop APP之前，按前文方法（Windows 用 CMD +set，Linux 用export）设置好所有ANTHROPIC_*环境变量。然后在终端中执行：

# Linux ./Claude-Desktop.AppImage # Windows Claude-Desktop.exe

APP 启动时会自动继承父进程的环境变量，无需任何 UI 操作。这是最稳定、最推荐的方式。

方式二：UI 设置面板（便捷但有坑）

Desktop APP 内置了一个 Settings 面板（通常在右上角齿轮图标），允许用户填写：

• Base URL:https://api.deepseek.com/anthropic
• API Key:sk-xxx
• Model:deepseek-v4-pro[1m]

但这里有个致命陷阱：UI 设置面板中的Model字段，不会自动添加[1m]后缀！它默认只显示deepseek-v4-pro。如果你直接保存，APP 会发送model=deepseek-v4-pro，触发 400 错误。你必须手动在Model输入框中，把deepseek-v4-pro改为deepseek-v4-pro[1m]，一个字符都不能少。

提示：UI 设置面板的值，会写入 APP 的本地配置文件（如~/.config/Claude-Desktop/config.json），下次启动时自动加载。但它不会覆盖已存在的环境变量。环境变量永远是最高优先级。

5.3 Windows 下 Desktop APP 的特殊问题：路径空格与长文件名

Windows 用户下载Claude-Desktop.exe后，若将其放在C:\Program Files\Claude Desktop\这样的路径下，启动时可能报错spawn claude ENOENT。原因是：

• C:\Program Files\路径包含空格；
• Electron 的spawn函数在 Windows 上对含空格路径的处理不健壮；
• APP 试图在C:\Program Files\Claude Desktop\目录下寻找claude命令，但claude实际安装在C:\Users\XXX\AppData\Roaming\npm\。

解决方案：

1. 将Claude-Desktop.exe移动到一个无空格、无中文、路径短的目录，例如D:\claude\;
2. 确保npm install -g @anthropic-ai/claude-code已成功执行，且claude命令全局可用；
3. 在D:\claude\目录下，按住Shift右键，选择“在此处打开 PowerShell 窗口”（或 CMD），然后执行.\Claude-Desktop.exe。

5.4 实用技巧：用 Desktop APP 的“Developer Mode”解锁高级功能

Desktop APP 隐藏了一个开发者模式，可绕过 UI 的诸多限制：

• 启动 APP 后，按Ctrl+Shift+I（Windows/Linux）或Cmd+Option+I（Mac）打开 DevTools；
• 在 Console 标签页中，输入：

  localStorage.setItem('developerMode', 'true'); location.reload();

• 重启 APP，右上角会出现一个新按钮 “Dev Tools”；
• 点击它，可手动编辑发送给 API 的原始 JSON 请求体，包括system提示词、tool_choice、max_tokens等 CLI 不暴露的参数。

这个模式让你能完全掌控请求，是调试复杂场景（如 Web Search、Tool Calling）的终极武器。

从 CLI 到 Desktop APP，不是功能的升级，而是交互范式的平移。CLI 给你原子级的控制力，Desktop APP 给你生产力的流畅感。而 DeepSeek，始终是那个沉默、强大、只认ANTHROPIC_*环境变量的后端引擎。你配置的不是“一个软件”，而是一整套人机协作的协议栈。当我第一次在 Desktop APP 里，把一个 500 行的 Python 脚本拖进去，输入请为这个脚本生成完整的单元测试，看到测试用例一行行生成出来时，我意识到：那些曾经让我熬夜调试的环境变量、那些被[1m]困扰的夜晚、那些在 PowerShell 里反复Unblock-File的操作，最终都凝结成了一个简单动作——点击发送。这，就是本地部署的价值。