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

> Claude 桌面版提示需要 Git：现在只有开了 Worktree 的会话才要 Git，Windows 版低于 1.49585.0 先更新，已装 Git 仍弹窗再查检测。

- URL: https://blog.laozhang.ai/zh/posts/claude-code-git-required-local-sessions
- Published: 2026-10-23
- Updated: 2026-10-23
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: Claude Code
- Tags: Claude Code, Claude 桌面版, Git is required for local sessions, 运行本地会话需要 Git, Git for Windows, Git Bash, CLAUDE_CODE_GIT_BASH_PATH, Worktree, 找不到 Git

---
在 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 报错说明](https://code.claude.com/docs/en/desktop#git-and-git-lfs-errors)）。

所以先查版本号：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，而真正需要的是更新应用。

| 情况 | 怎么判断 | 怎么处理 |
| --- | --- | --- |
| Windows 旧版桌面端，所有本地会话都要 Git | 版本是 1.x 且低于 1.49585.0；没开 Worktree 也弹窗；英文原文多为 "Git is required for local sessions. Download Git for Windows, or set the CLAUDE_CODE_GIT_BASH_PATH environment variable to your git executable…" | 更新应用，见下文“查看版本并更新” |
| 当前版本，会话开了 Worktree | 版本是 1.49585.0 或更新（包括 2.x、3.x）；关掉 Worktree 后能正常开会话 | 不需要隔离就关掉 Worktree；需要就安装 Git |
| Git 已安装，但应用找不到或跑不起来 | 终端里 `git --version` 正常，应用仍弹窗；Mac 新版提示 "Git is installed but isn't working" | Windows 查 `bash.exe` 路径、变量名和托盘进程；Mac 查许可协议、多余的 `git` 和完全磁盘访问 |
| 终端 CLI 的提示，不是桌面版弹窗 | 在 PowerShell 或 CMD 里运行 `claude` 时出现 "requires git-bash" 或 "requires either Git for Windows (for bash) or PowerShell" | 按 [Claude Code 安装教程：全平台完整设置指南（2026）](https://blog.laozhang.ai/zh/posts/claude-code-install) 处理 |

![判断“需要 Git”弹窗属于哪种情况：版本低于 1.49585.0 先更新，关掉 Worktree 弹窗消失就按需装 Git，否则查应用的 Git 检测](https://blog.laozhang.ai/posts/zh/claude-code-git-required-local-sessions/img/git-prompt-four-cases.webp)

弹窗措辞本身也能说明版本新旧。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 说明](https://code.claude.com/docs/en/desktop#run-a-session-in-its-own-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 部分](https://code.claude.com/docs/en/setup)）。所以“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 上的用户报告。

![CLAUDE_CODE_GIT_BASH_PATH 的三处核对：值填 Git\bin\bash.exe，变量名是 GIT 不是 GET，改完从托盘彻底退出再打开](https://blog.laozhang.ai/posts/zh/claude-code-git-required-local-sessions/img/windows-git-bash-path-checks.webp)

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 桌面版文档的本地会话环境变量说明](https://code.claude.com/docs/en/desktop)）。旧版的 Git 检查发生在会话启动之前，文档没有说这一步会不会读 settings.json，而 GitHub 上已有用户两处都设了，旧版弹窗仍在。

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

```json
{
  "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 次。这台机器上的正常输出如下，可以拿来和你的对照：

```bash
$ 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、本地控制和第三方界面](https://blog.laozhang.ai/zh/posts/claude-code-web-interface)。需要在本机文件夹里工作，可以改用终端里的 Claude Code，它在 Windows 上没有 Git for Windows 也能用 PowerShell 运行，安装方式见 [2026年Claude Code安装完全指南：Mac、Windows与Linux三平台教程](https://blog.laozhang.ai/zh/posts/how-to-install-claude-code)。弹窗过了、会话却报 "process exited with code 1"，那是另一个问题，按 [Claude Code process exited with code 1 怎么修：先分支定位再重装](https://blog.laozhang.ai/zh/posts/error-claude-code-process-exited-with-code-1) 排查。

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-10-23。

- [Claude Code 桌面版文档的 Git 报错说明](https://code.claude.com/docs/en/desktop) (code.claude.com)
- [Claude Code 安装文档的 Windows 部分](https://code.claude.com/docs/en/setup) (code.claude.com)