Claude 提示「运行本地会话需要 Git」：先看版本和 Worktree

在 Claude 桌面版（Claude Desktop）里打开 Code 标签页，选好文件夹或点新会话，就被一个弹窗挡住：英文界面写 "Git is required for local sessions" 或 "Git for Windows is required to run local sessions"，中文 Mac 界面写「运行本地会话需要 Git」。截至 2026 年 10 月 23 日，Claude Code 官方桌面版文档写明，只有开启 Worktree（为会话单独建一份工作树副本）的会话才需要 Git，而 Worktree 默认关闭；Windows 桌面版在 1.49585.0 之前对所有本地会话都先要求 Git，官方给的办法是更新应用（Claude Code 桌面版文档的 Git 报错说明）。

所以先查版本号：Windows 点 Help → About Claude，Mac 点 Claude → About Claude。Windows 版本是 1.x 且低于 1.49585.0，就用 Check for Updates… 更新（Mac 没有这个分界号，看到旧措辞也先更新）；已经是 1.49585.0 或更新（包括 2.x、3.x），再看会话有没有开 Worktree，不需要就关掉，需要就安装 Git（Windows 装 Git for Windows）。如果 Git 早就装好、版本也是新的，弹窗还在，问题在于应用找不到或跑不起 Git：Windows 查环境变量 CLAUDE_CODE_GIT_BASH_PATH 是否指向 bash.exe、改完有没有从托盘彻底退出，Mac 查 Xcode 许可协议、PATH 里多余的 git 和完全磁盘访问权限。这些都做过仍然弹窗，就别再重装 Git，改用云端会话或终端里的 Claude Code。

实际执行过的检查只有两项，都是 2026 年 10 月 23 日在一台 Mac 上做的：一是查看 macOS 26.1、Claude 桌面版 3.6556.2 的 Git 环境和应用日志，本地会话正常，日志里没有出现过 "Git is required"；二是检索同一版本安装包里的提示文字，旧措辞 "Git is required for local sessions" 已经不存在。没有在 Windows 上测试，下文的 Windows 步骤来自官方文档和 GitHub 上的用户报告。

“需要 Git”弹窗属于哪种情况：四种情况对照表

同一句“需要 Git”背后有四种情况，分清它们只需要三样信息：桌面版的版本号、这次会话有没有开 Worktree、终端里运行 git --version 能不能打印出版本号。先判断再动手，可以避开最常见的白忙：在旧版 Windows 桌面版上一遍遍重装 Git，而真正需要的是更新应用。

弹窗措辞本身也能说明版本新旧。2026 年 10 月 23 日检索 Mac 版 Claude 桌面版 3.6556.2 的安装包，"Git is required for local sessions" 和 "switch to a remote environment" 都是 0 处；这一版缺 Git 时提示 "Git is required but was not found. Run xcode-select --install in Terminal…"，Git 装了但调用失败时提示 "Git is installed but isn't working"，后面常跟一句建议给 Claude 授予完全磁盘访问权限。中文弹窗里的「也可以切换到远程环境」就是这句英文的译文，所以 Mac 上看到这类措辞，基本说明应用版本偏旧。Windows 版安装包没有检查过，那边的当前措辞只能从用户报告里看到。

Claude Code 本地会话一定要装 Git 吗：只有 Worktree 会话需要

不一定。截至 2026 年 10 月 23 日，Git 在 Claude 桌面版里必须承担的只有一件事：开了 Worktree 的会话要借助 Git worktree，在项目的 .claude/worktrees/ 目录下为会话建一份隔离的副本，让几个会话同时改代码时互不干扰。不开 Worktree，Claude 直接在你选的文件夹里工作，用不到这一步；所选文件夹本身不是 Git 仓库时，Worktree 也开不了（Claude Code 桌面版文档的 Worktree 说明）。

Worktree 开关的位置取决于界面布局。当前布局在输入框下方那一行，点项目文件夹控件，在里面关掉 Worktree；旧布局的环境选择器在输入框上方，开关是分支名旁边的 worktree 复选框；从保存的环境启动的会话按环境自己的 Worktree 设置走，要在编辑环境时改。关掉后再点新会话，弹窗消失，就属于上表第二种情况。

在 Windows 上，Git for Windows 还有另一个用途：它附带的 Git Bash 供 Claude Code 的 Bash 工具执行命令。Git Bash 不是单独的软件，安装 Git for Windows 时会一起装好；没装时 Claude Code 改用 PowerShell 工具，官方安装文档把 Git for Windows 列为可选项（Claude Code 安装文档的 Windows 部分）。所以“Windows 必须先装 Git，否则启动失败”只对 1.49585.0 之前的桌面版成立。另外，提示 "Git LFS is required by this repository but is not installed" 是仓库用了 Git LFS，和上面无关：从 git-lfs.com 安装 Git LFS，运行 git lfs install，再重启应用。

查看 Claude 桌面版版本并更新：低于 1.49585.0 先更新

版本号决定你是否需要碰 Git。1.49585.0 是官方文档给出的分界点，文档没有写它的发布日期；GitHub 上的 Windows 用户在 2026 年 9 月 9 日前后已经在用 1.49585，由此推断它大约在 9 月初推出。文档里还提到更晚的 v2.37337.0 和 v3.1623.0，所以 2.x、3.x 都比分界点新，只有低于 1.49585.0 的 1.x 才带着“任何本地会话都要 Git”的旧检查。这个分界点是针对 Windows 版写的；Mac 版遇到弹窗同样先更新到最新，再按下文 Mac 一节排查。

1. 查看版本：Mac 点菜单栏 Claude → About Claude，Windows 点 Help → About Claude；点一下版本号可以复制。
2. 比较版本：第一段是 2 或 3，已经比分界点新；第一段是 1，就看第二段数字，比 49585 小就是旧版，例如 1.24012.9 是旧版。
3. 更新：Mac 点 Claude → Check for Updates…，Windows 点 Help → Check for Updates…，更新完成后新开一个会话再试。菜单里找不到这一项，通常是所在组织关闭了自动更新，需要请管理员推送新版本。

装了 Git for Windows 仍弹窗：查 bash.exe 路径、变量名和托盘进程

版本已经是新的、会话确实要用 Worktree，或者暂时没法更新，就要让应用找到 Git Bash。官方用的变量是 CLAUDE_CODE_GIT_BASH_PATH，值是 bash.exe 的完整路径，默认安装位置下是 C:\Program Files\Git\bin\bash.exe。旧版弹窗写的是 "set … to your git executable"，容易让人填成 git.exe，但官方安装文档的示例填的是 bash.exe，以文档为准。下面的步骤来自官方文档和 GitHub 上的用户报告。

1. 找到 bash.exe：在 PowerShell 里运行 where.exe git，看 git.exe 装在哪个 Git 目录下（默认是 C:\Program Files\Git），这个目录里的 bin\bash.exe 就是要填的文件。可以再运行 Test-Path "C:\Program Files\Git\bin\bash.exe"，返回 True 说明文件存在；Git 装在 D 盘或用的是便携版，就把前面的目录换成实际位置。

2. 填 Git\bin\bash.exe，不填 git.exe，也不填 Git\usr\bin\bash.exe。GitHub 上一位用便携版 Git 的用户，把变量指向 usr\bin\bash.exe 时弹窗一直不消失，改成 bin\bash.exe 后才好。

3. 核对变量名：CLAUDE_CODE_GIT_BASH_PATH，中间是 GIT，不是 GET。名字差一个字母，应用就不会读取它；Windows 的变量名不区分大小写，大小写不是问题。

4. 设成用户环境变量。可以在 PowerShell 里运行下面这一行，也可以在“编辑账户的环境变量”窗口里手动新建：

   powershell复制

   [Environment]::SetEnvironmentVariable("CLAUDE_CODE_GIT_BASH_PATH", "C:\Program Files\Git\bin\bash.exe", "User")

5. 彻底退出 Claude 再打开。点窗口的 × 只是关掉窗口，Claude 还留在任务栏右下角的托盘里；展开托盘区，右键 Claude 图标选择退出，再打开任务管理器结束残留的 Claude 进程，然后重新启动应用。应用只在启动时读取环境变量，这一步不做，前面设的变量不会生效；仍不行就重启电脑。

6. 查看日志：用户报告的 Windows 日志位置是 %LOCALAPPDATA%\Claude\logs\main.log，官方文档没有写这个路径，Microsoft Store 版的位置可能不同。可以在 PowerShell 里运行 Select-String -Path "$env:LOCALAPPDATA\Claude\logs\main.log" -Pattern "git" | Select-Object -Last 20，看最后几行和 Git 有关的报错。

在 1.49585.0 之前的旧版上，这些都做对也可能消不掉弹窗。2026 年 3 月到 8 月，GitHub 上多位用户报告：变量设成系统级、指向 D:\Git\bin\bash.exe、在 settings.json 里也加了配置，弹窗照旧；Windows on ARM 的一位用户把 ARM64 版和 x64 版 Git 都换过，结果一样。Anthropic 的维护者把这些报告合并到同一个问题下关闭，其中一位用户在 8 月 28 日说重新登录后弹窗不见了，原因没有官方说明。所以在旧版上做完一轮就停手，先更新应用，不要反复重装 Git。

CLAUDE_CODE_GIT_BASH_PATH 写在系统环境变量还是 settings.json

要消掉桌面版的弹窗，写在 Windows 的用户环境变量或系统环境变量里。官方桌面版文档说明，Windows 版应用启动时继承用户和系统环境变量，但不读 PowerShell 配置文件（profile）；~/.claude/settings.json 里 env 设置的变量是交给每个本地会话里的 Claude Code 用的，而且同名变量已经存在于应用启动会话时的环境里，settings.json 里的值就会被忽略（Claude Code 桌面版文档的本地会话环境变量说明）。旧版的 Git 检查发生在会话启动之前，文档没有说这一步会不会读 settings.json，而 GitHub 上已有用户两处都设了，旧版弹窗仍在。

settings.json 的写法适合终端 CLI，或者会话里提示找不到 Git Bash 的情况。注意 JSON 里的反斜杠要写两个；gitBashPath 这类键不是文档里的设置项，GitHub 上加了它的用户弹窗照旧，不要照抄：

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Mac 已装命令行工具仍提示需要 Git：许可协议、多余的 git 和完全磁盘访问

先在“终端”里运行 git --version。能打印出版本号，说明 Git 本身没问题，弹窗来自应用这一侧的检测；打印的是 Xcode 许可协议的提示，或者没有版本号，就从下面第 1 步开始。弹窗让你运行的 xcode-select --install 只负责安装命令行工具（Command Line Tools），不处理许可协议，所以照做之后问题可能还在。以下做法来自 GitHub 上 Mac 用户的报告。

1. 同意 Xcode 许可协议：运行 sudo xcodebuild -license，按提示读完并输入 agree。装了完整 Xcode 且刚升级过 macOS 的，也可以打开一次 Xcode，点同意。
2. 查看应用日志：运行 grep 'error' ~/Library/Logs/Claude/main.log。看到 "You have not agreed to the Xcode license agreements"，回到第 1 步；看到 spawn … EACCES 跟着一个路径，说明应用把那个路径当成了 Git 去执行。
3. 清掉 PATH 里多余的 git：用户报告过的情况有 PATH 里一个空的 git 文件、自己放的 ~/bin/git、PATH 目录下一个名叫 git 的文件夹，以及 Homebrew 的 git 链接指向了 Cellar 里的目录。运行 which -a git 看排在第一的是什么，把日志里报 EACCES 的那个文件或文件夹删掉、改名，或者改成指向 /usr/bin/git 的链接。
4. 提示 "Git is installed but isn't working" 并建议授予完全磁盘访问权限时，打开 系统设置 → 隐私与安全性 → 完全磁盘访问权限，打开 Claude 的开关，然后按 ⌘Q 退出应用再重新打开。

这四步都正常、弹窗仍在，按上文的版本一节更新应用，因为 macOS 26 上还有一种误报，只出现在旧版本里。2026 年 8 月，一位 macOS 26.5.1、Claude 桌面版 1.32885.0 的用户在 GitHub 上分析过：旧版检测要求命令行工具目录里同时有 git 和 xcrun，而命令行工具 26.6 的这个目录里没有 xcrun，于是 /usr/bin/git 明明能用，应用还是显示安装 Git 的界面。

2026 年 10 月 23 日，在一台 macOS 26.1、Claude 桌面版 3.6556.2 的 Mac 上，命令行工具目录正是这种没有 xcrun 的布局，本地会话照常运行，2026 年 10 月 5 日以来的全部桌面版日志里 "Git is required" 出现 0 次。这台机器上的正常输出如下，可以拿来和你的对照：

$ git --version
git version 2.50.1 (Apple Git-155)
$ which -a git
/usr/bin/git
$ xcode-select -p
/Library/Developer/CommandLineTools
$ ls /Library/Developer/CommandLineTools/usr/bin/xcrun
ls: /Library/Developer/CommandLineTools/usr/bin/xcrun: No such file or directory
$ grep -c "Git is required" ~/Library/Logs/Claude/main.log
0

不再重装 Git 的时机：改走云端会话或终端 CLI

版本已经是 1.49585.0 或更新，终端里 git --version 正常，Windows 的变量或 Mac 的许可协议和日志都查过，也彻底退出重开过，弹窗仍在，就到了该停手的时候。重装 Git 解决不了应用的检测问题，这时把版本号和 main.log 里与 Git 有关的报错附在 GitHub 的 anthropics/claude-code 问题区，同时先换一条不依赖这一步检测的路线把活干完。

云端会话在 Anthropic 的虚拟机里克隆你的 GitHub 仓库，不需要本机 Git，但要先连接 GitHub 账号，适合代码已经在 GitHub 上、不依赖本机工具和配置的工作，入口和限制见 Claude Code 有网页版吗：先分清云端 Web、本地控制和第三方界面。需要在本机文件夹里工作，可以改用终端里的 Claude Code，它在 Windows 上没有 Git for Windows 也能用 PowerShell 运行，安装方式见 2026年Claude Code安装完全指南：Mac、Windows与Linux三平台教程。弹窗过了、会话却报 "process exited with code 1"，那是另一个问题，按 Claude Code process exited with code 1 怎么修：先分支定位再重装 排查。