From f8cbb1a4a46bb0e9453d697960de39ce4a20eef7 Mon Sep 17 00:00:00 2001 From: 1939869736luosi <1939869736luosi@users.noreply.github.com> Date: Thu, 19 Feb 2026 18:12:17 +0800 Subject: [PATCH 1/3] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20Git=20Bash=20?= =?UTF-8?q?=E6=A3=80=E6=B5=8B=E4=BF=AE=E5=A4=8D=E3=80=81API=20=E9=85=8D?= =?UTF-8?q?=E7=BD=AE=E6=9B=B4=E6=96=B0=E3=80=81Antigravity=20=E5=85=BC?= =?UTF-8?q?=E5=AE=B9=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 1.3.1 节：Git Bash 检测报错修复（已知 bug + 一键补丁脚本） - 更新 1.4.1：补充 apiKeyHelper 推荐配置方式 - 更新 1.4.2：bat 脚本增加 CLAUDE_CODE_GIT_BASH_PATH - 第 4 节：补充 Antigravity IDE 说明 + environmentVariables 格式警告 - 新增第 5 节：更换 API 提供商快速指南 --- README.md | 135 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 133 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 50ac1d3..c59b52c 100644 --- a/README.md +++ b/README.md @@ -46,13 +46,87 @@ claude --version --- +### 1.3.1 ⚠️ 已知问题：Git Bash 检测报错 + +> [!WARNING] +> 这是一个 [GitHub 上的已知 bug](https://github.com/anthropics/claude-code/issues)，大量用户反馈即使正确安装了 Git 仍会报错。 + +**问题现象**：在 VS Code 或 Antigravity 中打开 Claude Code 扩展时，报错： + +``` +Claude Code on Windows requires git-bash (https://git-scm.com/downloads/win). +If installed but not in PATH, set environment variable pointing to your bash.exe... +``` + +**根本原因**：扩展内部用 `where.exe git` 命令检测 Git 是否存在。但 VS Code / Antigravity 的进程环境可能缺少 `System32` 或 Git `cmd` 目录的 PATH，导致检测失败。 + +> [!CAUTION] +> **`CLAUDE_CODE_GIT_BASH_PATH` 环境变量不能解决此问题！** 很多教程建议设置这个变量，但扩展的初始检测函数（`ZD6()`）并不读取此变量，它只执行 `where.exe git`。这个变量是给后续功能使用的，不影响初始检测。 + +**✅ 解决方案：修补扩展源码** + +在 PowerShell 中运行以下命令（一键修补）： + +```powershell +# 定位 extension.js 文件 +$file = (Get-ChildItem "$env:USERPROFILE\.vscode\extensions\anthropic.claude-code-*\extension.js" -ErrorAction SilentlyContinue) ?? + (Get-ChildItem "$env:USERPROFILE\.antigravity\extensions\anthropic.claude-code-*\extension.js" -ErrorAction SilentlyContinue) + +if (-not $file) { Write-Host "ERROR: Claude Code extension not found"; return } + +$content = [System.IO.File]::ReadAllText($file.FullName) + +# 查找并替换 git-bash 检测逻辑 +$pattern = 'catch{throw Error("Claude Code on Windows requires git-bash' +$idx = $content.IndexOf($pattern) + +if ($idx -ge 0) { + # 找到完整的 catch 块并替换 + $catchStart = $idx + $catchEnd = $content.IndexOf(')}")', $idx) + 3 + $oldBlock = $content.Substring($catchStart, $catchEnd - $catchStart) + $content = $content.Replace($oldBlock, 'catch{return}') + [System.IO.File]::WriteAllText($file.FullName, $content) + Write-Host "SUCCESS: Git-bash check bypassed in $($file.FullName)" +} else { + Write-Host "Already patched or pattern changed in new version" +} +``` + +> [!IMPORTANT] +> **扩展更新会覆盖补丁！** 建议： +> 1. 在 VS Code / Antigravity 设置中添加 `"extensions.autoUpdate": false` 关闭自动更新 +> 2. 保存上面的补丁命令，扩展更新后重新运行即可 + +--- + ### 1.4 配置环境变量 > 最好下面两个一起配置 #### 1.4.1 配置 settings.json 文件 -创建（如果不存在）或编辑 `C:\Users\用户名\.claude\settings.json`，输入以下值并保存： +创建（如果不存在）或编辑 `C:\Users\用户名\.claude\settings.json`。 + +**方式一：使用 `apiKeyHelper`（推荐 ⭐）** + +通过命令返回 API Key，更安全（Key 不直接明文写在配置中）： + +```json +{ + "apiKeyHelper": "echo 替换为您的API-Key", + "env": { + "ANTHROPIC_BASE_URL": "https://your-api-provider.com/v1/", + "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "12000" + }, + "permissions": { + "allow": [], + "deny": [] + } +} +``` + +**方式二：直接写在 `env` 中** ```json { @@ -68,6 +142,8 @@ claude --version } ``` +> 两种方式的区别：`apiKeyHelper` 通过执行命令获取 Key，不会在配置文件中暴露明文密钥，更适合团队共享或版本控制场景。`env.ANTHROPIC_AUTH_TOKEN` 直接写死 Key，简单直接但安全性稍差。 + --- #### 1.4.2 配置环境变量 @@ -95,6 +171,7 @@ echo Setting environment variables... setx ANTHROPIC_AUTH_TOKEN "%API_KEY%" setx ANTHROPIC_BASE_URL "https://www.fucheers.top" setx CLAUDE_CODE_MAX_OUTPUT_TOKENS "12000" +setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe" echo. echo ======================================== @@ -105,6 +182,7 @@ echo Environment variables set: echo ANTHROPIC_AUTH_TOKEN = %API_KEY% echo ANTHROPIC_BASE_URL = https://www.fucheers.top echo CLAUDE_CODE_MAX_OUTPUT_TOKENS = 12000 +echo CLAUDE_CODE_GIT_BASH_PATH = C:\Program Files\Git\bin\bash.exe echo. echo Please restart your terminal for changes to take effect. echo. @@ -113,6 +191,8 @@ pause 下载这个 bat 文件，输入 API Key 回车即设置完成。 +> **注意**：`CLAUDE_CODE_GIT_BASH_PATH` 主要用于 CLI 版 `claude` 命令。如果 VS Code/Antigravity 扩展仍报错，请参考 [1.3.1 节](#131-️-已知问题git-bash-检测报错) 使用源码补丁方案。 + --- ### 1.5 打开 Claude Code 终端 @@ -192,6 +272,13 @@ claude ## 4. VS Code 扩展与 Claude Code CLI +> [!TIP] +> 以下内容同样适用于 **Antigravity IDE**（Google 基于 VS Code 的 fork）。两者的区别仅在扩展安装路径： +> - VS Code：`%USERPROFILE%\.vscode\extensions\anthropic.claude-code-*\` +> - Antigravity：`%USERPROFILE%\.antigravity\extensions\anthropic.claude-code-*\` +> +> 设置界面和操作方式完全一致。 + ### 扩展设置 `~/.claude/settings.json` 中的 Claude Code 设置，在 VS Code 和 CLI 之间共享，用于配置环境变量、hooks 和 MCP servers。有关详细信息，请参阅 [Settings](https://code.claude.com/docs/en/settings)。 @@ -213,11 +300,26 @@ claude | `enableNewConversationShortcut` | `true` | 启用 Cmd/Ctrl+N 以开始新对话 | | `hideOnboarding` | `false` | 隐藏入门引导卡片（生产环境推荐） | | `respectGitIgnore` | `true` | 从文件搜索中排除 `.gitignore` 匹配项 | -| `environmentVariables` | `[]` | 为 Claude 进程设置环境变量。共享配置请使用 Claude Code 设置 | +| `environmentVariables` | `{}` | 为 Claude 进程设置环境变量。共享配置请使用 Claude Code 设置 | | **`disableLoginPrompt`** | **`false`** | **跳过身份验证提示（用于第三方提供商设置）** | | `allowDangerouslySkipPermissions` | `false` | 跳过所有权限检查请求，**谨慎使用** | | `claudeProcessWrapper` | `-` | 用于启动 Claude 进程的可执行文件路径 | +> [!CAUTION] +> **`environmentVariables` 必须使用对象格式 `{}`，不能用数组 `[]`！** +> +> 错误写法会导致 `v is not iterable` 报错，使扩展无法启动。 +> +> ```json +> // ❌ 错误：使用数组 +> "claudeCode.environmentVariables": ["ANTHROPIC_BASE_URL=https://..."] +> +> // ✅ 正确：使用对象 +> "claudeCode.environmentVariables": { +> "ANTHROPIC_BASE_URL": "https://..." +> } +> ``` + ### 关键设置：Disable Login Prompt > [!IMPORTANT] @@ -247,6 +349,35 @@ Claude Code 同时提供 VS Code 扩展（图形界面）和 CLI（终端命令 --- +## 5. 🔄 更换 API 提供商 + +当需要更换 API 服务商（例如从 Kimi 切换到其他兼容 Anthropic API 格式的提供商），**只需修改 1 个文件的 2 个字段**： + +### 修改文件 + +`C:\Users\用户名\.claude\settings.json` + +```diff + { +- "apiKeyHelper": "echo sk-old-key-xxx", ++ "apiKeyHelper": "echo sk-new-key-xxx", + "env": { +- "ANTHROPIC_BASE_URL": "https://old-provider.com/v1/" ++ "ANTHROPIC_BASE_URL": "https://new-provider.com/v1/" + } + } +``` + +### 操作步骤 + +1. 编辑 `~/.claude/settings.json`，修改 `apiKeyHelper` 和 `ANTHROPIC_BASE_URL` +2. 在 VS Code / Antigravity 中按 `Ctrl+Shift+P` → 输入 `Reload Window` 回车 +3. 完成 ✅ + +> 如果使用 CLI 方式（终端中运行 `claude`），关闭终端重新打开即可。 + +--- + ## 📎 相关资源 | 资源 | 说明 | From 576fecdaf486ea8b281f730ccc9496c2ff2bd5c9 Mon Sep 17 00:00:00 2001 From: 1939869736luosi <1939869736luosi@users.noreply.github.com> Date: Wed, 25 Feb 2026 18:39:58 +0800 Subject: [PATCH 2/3] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E6=96=87?= =?UTF-8?q?=E4=BB=B6=E8=B7=AF=E5=BE=84=E6=A0=87=E6=B3=A8=E5=92=8C=E6=9B=B4?= =?UTF-8?q?=E6=8D=A2=20API=20=E8=AF=A6=E7=BB=86=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 152 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 117 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index c59b52c..fcc72d0 100644 --- a/README.md +++ b/README.md @@ -106,43 +106,100 @@ if ($idx -ge 0) { #### 1.4.1 配置 settings.json 文件 -创建（如果不存在）或编辑 `C:\Users\用户名\.claude\settings.json`。 +> [!IMPORTANT] +> **文件路径**：`C:\Users\<你的用户名>\.claude\settings.json` +> +> 例如用户名为 `Lenovo`，则完整路径为：`C:\Users\Lenovo\.claude\settings.json` +> +> 如果 `.claude` 文件夹或 `settings.json` 不存在，请手动创建。 -**方式一：使用 `apiKeyHelper`（推荐 ⭐）** +这个文件是 Claude Code **最核心的配置文件**，控制 API 连接、权限和 MCP 服务器。以下是完整的配置说明。 -通过命令返回 API Key，更安全（Key 不直接明文写在配置中）： +**API Key 配置（二选一）** -```json -{ - "apiKeyHelper": "echo 替换为您的API-Key", - "env": { - "ANTHROPIC_BASE_URL": "https://your-api-provider.com/v1/", - "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "12000" - }, - "permissions": { - "allow": [], - "deny": [] - } -} -``` +| 方式 | 字段 | 示例值 | 安全性 | 适用场景 | +|------|------|--------|--------|----------| +| **方式一（推荐 ⭐）** | `apiKeyHelper` | `"echo sk-your-key"` | 高（Key 不明文存储） | 团队共享、版本控制 | +| 方式二 | `env.ANTHROPIC_AUTH_TOKEN` | `"sk-your-key"` | 低（明文写死） | 个人快速使用 | -**方式二：直接写在 `env` 中** +**完整配置示例（含 MCP 服务器）** ```json { + // ======================== + // 🔑 API 配置（更换服务商时只改这两行） + // ======================== + "apiKeyHelper": "echo sk-your-api-key-here", // ← 改这里：换成新的 API Key "env": { - "ANTHROPIC_AUTH_TOKEN": "替换为您的API Key", - "ANTHROPIC_BASE_URL": "https://www.fucheers.top", - "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "12000" + "ANTHROPIC_BASE_URL": "https://api.kimi.com/coding/", // ← 改这里：换成新的 API 地址 + "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe" }, + + // ======================== + // 🔒 权限控制 + // ======================== "permissions": { - "allow": [], + "allow": [ + "Bash(ffmpeg:*)" // 允许 Claude 执行 ffmpeg 命令 + ], "deny": [] + }, + + // ======================== + // 🔌 MCP 服务器（可选，按需添加） + // ======================== + "mcpServers": { + "granola": { + "type": "sse", + "url": "https://mcp.granola.ai/mcp" + }, + "v0": { + "command": "D:\\Program Files\\nodejs\\npx.cmd", + "args": ["-y", "v0-mcp@latest"], + "timeout": 60000, + "env": { + "V0_API_KEY": "your-v0-api-key-here", + "PATH": "D:\\Program Files\\nodejs;C:\\Windows\\System32;C:\\Windows" + } + }, + "weixin-reader": { + "command": "C:\\Users\\用户名\\AppData\\Local\\Programs\\Python\\Python312\\python.exe", + "args": ["D:\\your-project\\wexin-read-mcp\\src\\server.py"], + "timeout": 30000 + }, + "ChatPRD": { + "command": "D:\\Program Files\\nodejs\\npx.cmd", + "args": ["-y", "mcp-remote", "https://app.chatprd.ai/mcp"], + "timeout": 60000, + "env": { + "PATH": "D:\\Program Files\\nodejs;C:\\Windows\\System32;C:\\Windows" + } + } } } ``` -> 两种方式的区别：`apiKeyHelper` 通过执行命令获取 Key，不会在配置文件中暴露明文密钥，更适合团队共享或版本控制场景。`env.ANTHROPIC_AUTH_TOKEN` 直接写死 Key，简单直接但安全性稍差。 +> [!NOTE] +> 上面 JSON 中的注释仅用于说明，**实际使用时请删除所有 `//` 注释**（JSON 标准不支持注释）。 + +**字段逐行解释** + +| 字段 | 作用 | 何时需要修改 | +|------|------|-------------| +| `apiKeyHelper` | 通过命令返回 API Key | **更换 API 服务商时** | +| `env.ANTHROPIC_BASE_URL` | API 服务商地址 | **更换 API 服务商时** | +| `env.CLAUDE_CODE_GIT_BASH_PATH` | Git Bash 路径 | 仅 Git 安装路径不同时 | +| `permissions.allow` | 允许 Claude 自动执行的命令 | 按需添加 | +| `mcpServers.*` | MCP 服务器配置 | 添加/删除 MCP 服务时 | + +> [!TIP] +> **关于 MCP 服务器**： +> - `granola`：会议记录管理，通过 SSE 连接 +> - `v0`：Vercel v0 UI 原型生成，需要 [V0 API Key](https://v0.dev) +> - `weixin-reader`：微信公众号文章抓取（Python 实现） +> - `ChatPRD`：AI 产品文档生成 +> +> 每个 MCP 服务器的 `env.PATH` 需要手动补全 `nodejs` 和 `System32` 路径，因为 VS Code / Antigravity 的进程 PATH 可能不完整。 --- @@ -351,30 +408,55 @@ Claude Code 同时提供 VS Code 扩展（图形界面）和 CLI（终端命令 ## 5. 🔄 更换 API 提供商 -当需要更换 API 服务商（例如从 Kimi 切换到其他兼容 Anthropic API 格式的提供商），**只需修改 1 个文件的 2 个字段**： +当需要更换 API 服务商时（例如从 Kimi 切换到其他兼容 Anthropic API 格式的服务商），**只需修改 1 个文件的 2 个字段**。 + +### 📁 需要修改的文件 -### 修改文件 +``` +C:\Users\<你的用户名>\.claude\settings.json +``` + +### 🔧 需要修改的字段 + +| 字段 | 改什么 | 示例 | +|------|--------|------| +| `apiKeyHelper` | `echo` 后面的 API Key | `"echo sk-new-xxx"` | +| `env.ANTHROPIC_BASE_URL` | API 服务商的地址 | `"https://new-provider.com/v1/"` | -`C:\Users\用户名\.claude\settings.json` +### 📝 修改示例（diff 对比） ```diff { -- "apiKeyHelper": "echo sk-old-key-xxx", -+ "apiKeyHelper": "echo sk-new-key-xxx", +- "apiKeyHelper": "echo sk-kimi-旧的Key", ++ "apiKeyHelper": "echo sk-new-新的Key", "env": { -- "ANTHROPIC_BASE_URL": "https://old-provider.com/v1/" +- "ANTHROPIC_BASE_URL": "https://api.kimi.com/coding/" + "ANTHROPIC_BASE_URL": "https://new-provider.com/v1/" } } ``` -### 操作步骤 - -1. 编辑 `~/.claude/settings.json`，修改 `apiKeyHelper` 和 `ANTHROPIC_BASE_URL` -2. 在 VS Code / Antigravity 中按 `Ctrl+Shift+P` → 输入 `Reload Window` 回车 -3. 完成 ✅ - -> 如果使用 CLI 方式（终端中运行 `claude`），关闭终端重新打开即可。 +> [!WARNING] +> **其他字段不要动！** `permissions`、`mcpServers`、`CLAUDE_CODE_GIT_BASH_PATH` 等字段与 API 服务商无关，改了可能导致功能异常。 + +### ✅ 完整操作步骤 + +1. 用任意编辑器打开 `C:\Users\<你的用户名>\.claude\settings.json` +2. 找到 `apiKeyHelper` 行 → 把 `echo` 后面的内容换成新的 API Key +3. 找到 `ANTHROPIC_BASE_URL` 行 → 把 URL 换成新服务商的地址 +4. 保存文件 +5. **使生效**（二选一）： + - **VS Code / Antigravity**：按 `Ctrl+Shift+P` → 输入 `Reload Window` 回车 + - **CLI 终端**：关闭终端窗口，重新打开后运行 `claude` +6. 输入 `/status` 确认已连接到新的服务商 ✅ + +### 🔍 常见第三方 API 服务商参考 + +| 服务商 | `ANTHROPIC_BASE_URL` 格式 | +|--------|---------------------------| +| Kimi | `https://api.kimi.com/coding/` | +| Fucheers | `https://www.fucheers.top` | +| 其他兼容服务商 | 参考服务商文档中的 Base URL | --- From 185ae4d567c2a36171fc85d1801e76330710bbdb Mon Sep 17 00:00:00 2001 From: 1939869736luosi <1939869736luosi@users.noreply.github.com> Date: Wed, 25 Feb 2026 18:48:22 +0800 Subject: [PATCH 3/3] =?UTF-8?q?fix:=20JSON=20=E4=BB=A3=E7=A0=81=E5=9D=97?= =?UTF-8?q?=E6=94=B9=E7=94=A8=20jsonc=20=E9=81=BF=E5=85=8D=E6=B3=A8?= =?UTF-8?q?=E9=87=8A=E5=AF=BC=E8=87=B4=E8=AF=AD=E6=B3=95=E9=AB=98=E4=BA=AE?= =?UTF-8?q?=E9=94=99=E8=AF=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fcc72d0..a3f98f9 100644 --- a/README.md +++ b/README.md @@ -124,7 +124,7 @@ if ($idx -ge 0) { **完整配置示例（含 MCP 服务器）** -```json +```jsonc { // ======================== // 🔑 API 配置（更换服务商时只改这两行）