Claude Code Windows 配置指南#

---

一键配置#

直接复制下面这段完整的 Prompt，粘贴到 Claude Code 主会话中。它会自动检查并安装 pwsh，然后把 CLAUDE.md 和 settings.json 的所有核心配置合并落地，且保留现有内容不覆盖。

把下面四处配置落地到我本地，保留原有内容不要覆盖，合并而不是替换：

【0】前置检查：验证并安装 PowerShell 7+ (pwsh)
- 先执行 `pwsh --version` 检查是否已安装。
- 如果未安装或命令找不到，请自动执行 `winget install --id Microsoft.PowerShell --source winget --accept-source-agreements --accept-package-agreements` 进行安装。
- 安装完成后，再次执行 `pwsh --version` 确认安装成功。

【1】在 ~/.claude/CLAUDE.md 顶部追加以下三段 markdown：

```markdown
# Global PowerShell Rules (Windows + pwsh 7+)

## Shell Preference
- **默认禁止调用 Bash Tool。** 需要执行 shell 命令时只能用 PowerShell Tool（pwsh.exe）——这是工具层的硬约束。Unix 惯用语法（`ls | head`、`grep`、`curl`、`find`、`cat`）不是借口，改用对应 cmdlet（`Get-ChildItem | Select-Object -First N`、`Select-String`、`Invoke-WebRequest`、`Get-ChildItem -Recurse`、`Get-Content`）。
- 列文件用 Glob，读文件用 Read，搜内容用 Grep——dedicated tool 优先级仍然高于 shell。
- 路径一律使用 Windows 原生风格（`C:\` 或 `$env:USERPROFILE`），避免 `/` 路径；只有在调用 git/POSIX 工具时可临时接受 `/c/...`。

## Bash Tool 例外清单（仅在以下场景允许）
Bash Tool 在默认禁用之外，**仅**这几类情况可以使用，且必须在调用时一句话说明原因：

1. **用户明确指令**："用 bash"、"跑 sh 脚本"、"在 MINGW 下执行" 等显式要求。
2. **必须依赖 POSIX 行为的脚本**：仓库里已有的 `.sh` 文件、`Makefile` 目标、`configure` 脚本——这些用 pwsh 翻译会失真，直接 Bash 调用更稳。
3. **Git hooks / pre-commit 框架**：很多 hook 假定 `/bin/sh`，pwsh 包一层反而出错。直接让 git 自己跑 Bash。
4. **跨平台 CI 脚本本地复现**：当目标是验证 `.github/workflows/*.yml` 里的 shell 步骤是否能跑通时，用 Bash 还原原始行为。
5. **MINGW-only 二进制**：`ssh-agent`、`gpg`、`openssl` 等如果只在 MSYS 环境下能正常工作。

不在上述清单的，一律走 PowerShell。模糊地带先问用户。

## PowerShell 实战注意
- 文件写出默认 UTF-8 无 BOM（pwsh 7 默认行为）；用 `Out-File`/`Set-Content` 时不要手动加 `-Encoding utf8BOM`，除非目标工具明确要求 BOM。
- 调用带空格路径的原生 exe 用 call 操作符：`& "C:\Program Files\App\app.exe" arg1`。
- 给原生命令传 `-`、`@`、`--` 开头的参数时用 stop-parsing token：`git log --% --format=%H`。
- 多行字符串（commit message、文件内容）用单引号 here-string，**闭合 `'@` 必须顶格**：
  ```powershell
  git commit -m @'
  feat: add foo

  body line
  '@
  ```
- `-ErrorAction SilentlyContinue` 只压制输出不改退出码；要真正吞错用 `try { ... -ErrorAction Stop } catch {}`。
- 严禁 `Invoke-Expression` 拼接用户输入——命令注入风险。
- 严禁 `New-Item -Force` 用在已存在的文件上，会清空内容。
```

【2】把以下 env 和 defaultShell 合并进 ~/.claude/settings.json（保留其他字段）：

```json
{
  "env": {
    "API_FORCE_IDLE_TIMEOUT": "0",
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "false",
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1",
    "POWERSHELL_TELEMETRY_OPTOUT": "1"
  },
  "defaultShell": "powershell"
}
```

【3】合并进 ~/.claude/settings.json 的 permissions（保留已有其他元素）：

```json
{
  "permissions": {
    "allow": ["PowerShell", "Read", "Write", "Edit", "MultiEdit", "Glob", "WebFetch", "WebSearch", "NotebookRead", "NotebookEdit"],
    "deny": ["Bash"]
  }
}
```

改完列出具体改动点，并告诉我是否需要重启终端。

---

强制使用 PowerShell (pwsh)#

Windows 下使用 pwsh 替代 Bash 可获得 2.7~31 倍的性能提升。

前置条件#

安装 PowerShell 7+（非 Windows 自带的 5.1）：

# 检查是否已安装
pwsh --version

# 若未安装，使用 winget 安装
winget install --id Microsoft.PowerShell --source winget

手动配置步骤#

---

解决第三方 API 超时问题#

作用：禁用 API 空闲超时限制。

在使用第三方 API（中转站或国内模型）时，由于网络链路较长或模型推理（如深度思考模式）耗时较久，极易触发中间网关的空闲超时断开，导致报错 API Error: The operation timed out.。

---

开启多智能体团队协作#

作用：启用实验性的「多智能体团队协作」（Agent Teams）功能。

开启后，Claude Code 可以拉起多个独立的 AI 实例组成「开发团队」，并行处理复杂任务：

• Team Lead（主会话）：负责拆解任务、分配工作、汇总最终结果。
• Teammates（队友）：各自拥有独立的上下文窗口，可以同时编辑不同的文件或执行不同的子任务。
• 通信机制：队友之间可通过内置的「邮箱系统」互相通信、共享任务进度。

适用场景：多模块并行开发、大规模代码重构、复杂的跨文件审查。

---

屏蔽非必要网络流量#

作用：阻止 Claude Code 向 Anthropic 官方服务器发送非核心网络请求。

Claude Code 默认会在后台发送一些遥测、分析、后台同步等请求。对于使用第三方 API 或处于受限网络环境的用户，这些请求不仅无用，还可能导致报错。开启此变量后：

• 减少报错：避免因官方服务器不可达或 API Key 不匹配而产生的后台鉴权报错。
• 提升速度：减少无用的 DNS 查询和网络握手，让 CC 更专注于核心的代码生成请求。
• 保护隐私：配合关闭遥测，最大限度减少后台数据上报。

---

提高 Claude Code 缓存命中率#

作用：关闭计费归因 Header。

在使用第三方 API（国内模型、中转站）时，关闭 billing header 可大幅提升跨会话的缓存命中率，节省约 90% 费用，速度提升约 8 倍。

---

完整配置参考#

将所有配置整合后的完整 settings.json 示例：

{
  "env": {
    "API_FORCE_IDLE_TIMEOUT": "0",
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "false",
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1",
    "POWERSHELL_TELEMETRY_OPTOUT": "1"
  },
  "defaultShell": "powershell",
  "permissions": {
    "allow": [
      "PowerShell", "Read", "Write", "Edit", "MultiEdit",
      "Glob", "WebFetch", "WebSearch", "NotebookRead", "NotebookEdit"
    ],
    "deny": ["Bash"]
  }
}

---

附录：Unix → PowerShell 命令速查#

Unix 命令	PowerShell 替代
ls / find	Get-ChildItem
grep	Select-String
cat	Get-Content（或直接用 Read 工具）
head -N / tail -N	Select-Object -First/-Last N
wc -l	Measure-Object -Line
curl / wget	Invoke-WebRequest / Invoke-RestMethod
sort / uniq	Sort-Object / Group-Object