问题Claude Desktop 3P 版 “Host Claude Code binary not available”过程Claude Desktop在mac上首次安装后对话报错使用codex、claude、trae修复都无效最终使用WorkBuddy经过近十轮尝试和修复后终于解决让WorkBuddy 将修复过程打包成skill便于后续更新时复用根因Claude Desktop 需要一个本地的 Claude Code 二进制来驱动对话功能。在国内环境下downloads.claude.ai CDN 不可达无法自动下载。手动放置二进制时经历了两个层面的问题第一层路径错误3P 部署版使用 userData 目录为 Claude-3p而非 Claude。CCD 管理器的 storageDir userData “claude-code”所以实际期望路径是~/Library/Application Support/Claude-3p/claude-code/2.1.187/claude.app/Contents/MacOS/claude而我们多次把二进制放在了 ~/Library/Application Support/Claude/claude-code/…。第二层代码签名从 GitHub 镜像下载的二进制带有原始 Anthropic Developer ID 签名在别的机器上运行时会触发 macOS 的 Code Signature Invalid Page 检测进程被 SIGKILL 杀死。修复方案三步步骤 操作获取正确版本二进制从 GitHub 镜像下载 Claude Code 2.1.187 (darwin-arm64)精确匹配 app.asar manifest 中声明的版本重新签名codesign --force --deep --sign - 用 ad-hoc 签名替换失效的原始签名解决 SIGKILL 崩溃放置到正确目录创建 bundle 结构 Claude-3p/claude-code/2.1.187/claude.app/Contents/MacOS/claude并写入 .verified 文件bundle checksum: 2c83be71…CCD 验证链路getBinaryPathIfReady()→ getHostTarget() → useBundletrue, platformdarwin-arm64→ getBinaryPathForTarget() → storageDir/2.1.187/claude.app/Contents/MacOS/claude→ binaryExistsForTarget()→ .verified 文件内容 manifest.bundle.checksum ✓→ N4e() Mach-O header 检查 (MH_MAGIC_64 CPU_ARM64) ✓→ binary 可用启动会话 ✓关键教训Claude Desktop 3P 版的 userData 路径是 Claude-3p不是 Claude二进制版本号必须与 app.asar manifest 中的 requiredVersion 精确匹配macOS 对非本机签名的 Mach-O 二进制会触发 CODESIGNING 杀进程ad-hoc 重签名即可解决downloads.claude.ai 在国内完全不可达需要走镜像Skill总结name: claude-desktop-ccd-fixdescription: “Claude Desktop 在中国大陆使用时报 Host Claude Code binary not available 错误的修复方案。downloads.claude.ai CDN 在国内不可达导致 Claude Code 二进制无法自动下载。适用于 Claude Desktop 1.15962.1 及以上版本1P 和 3P 部署模式均适用。触发词Claude Desktop 二进制错误、CCD binary not available、Claude Code 下载失败、claude-code-releases、Host Claude Code binary not available、Claude Desktop 重新安装修复。”agent_created: trueClaude Desktop CCD Binary Fix概述Claude Desktop 需要本地 Claude Code 二进制才能驱动对话功能。在国内环境下downloads.claude.aiCDN 不可达导致自动下载失败报错 “Host Claude Code binary not available”。本 skill 提供手动修复方案从 GitHub 镜像下载二进制、绕过代码签名检查、放置到正确位置。触发场景Claude Desktop 启动后聊天窗口提示 “Host Claude Code binary not available. Check that the download completed.”重新安装 Claude Desktop 后需要重新修复Claude Desktop 主日志中出现[CCD] Download attempt failed或ERR_CONNECTION_TIMED_OUT修复流程第一步获取 manifest 信息Claude Desktop 的 app.asar 中嵌入了 CCD 二进制 manifest包含所需版本号和校验和。必须先提取这些信息。# 1. 解压 app.asarnpx asar extract /Applications/Claude.app/Contents/Resources/app.asar /tmp/claude-asar-extract# 2. 提取 manifestbft() 函数返回的 JSONpython3-c import re with open(/tmp/claude-asar-extract/.vite/build/index.js, r) as f: content f.read() idx content.find(darwin-arm64) if idx 0: start max(0, idx - 2000) end min(len(content), idx 1500) chunk content[start:end] # 提取完整 manifest JSON m re.search(rfunction bft\(\)\{return JSON\.parse\(\x27(.?)\x27\), chunk) if m: print(m.group(1)) else: # 回退打印包含 darwin-arm64 的附近代码 for s in re.finditer(r\{\version\:\[^\]\.?darwin-arm64.?\}, chunk): print(s.group()) 从 manifest 中获取三个关键值以 v2.1.187 为例version:2.1.187→ 所需二进制版本platforms.darwin-arm64.bundle.checksum:2c83be71...→ bundle .verified 校验和platforms.darwin-arm64.checksum:658417c6...→ 裸二进制校验和备用第二步确定 userData 路径CCD 管理器使用app.getPath(userData) /claude-code作为存储目录。userData 取决于部署模式1P 模式deploymentMode1p~/Library/Application Support/Claude3P 模式deploymentMode3p~/Library/Application Support/Claude-3p判断方法启动 Claude Desktop 后查看进程命令行psaux|grep/Applications/Claude.app/Contents/MacOS/Claude$|grep-ouser-data-dir[^ ]*# 如果有 user-data-dir.../Claude-3p → 3P 模式# 如果没有 user-data-dir 参数 → 1P 模式默认 Claude也可以从渲染进程的 telemetry 中查看psaux|grepClaude Helper (Renderer)|grep-odeploymentMode:[^]*|head-1第三步下载 Claude Code 二进制从 GitHub 镜像下载精确版本的二进制国内直连 GitHub 可能失败使用ghfast.top加速VERSION2.1.187# 从 manifest 获取USER_DATA$HOME/Library/Application Support/Claude# 1P 模式3P 则为 Claude-3pDST$USER_DATA/claude-code/$VERSIONmkdir-p$DST# macOS ARM 版本curl-L-o$DST/claude\https://ghfast.top/https://github.com/ProjectAILeap/claude-code-releases/releases/download/v$VERSION/claude-$VERSION-darwin-arm64# macOS x64 版本备用# curl -L -o $DST/claude \# https://ghfast.top/https://github.com/ProjectAILeap/claude-code-releases/releases/download/v$VERSION/claude-$VERSION-darwin-x64如果ghfast.top不可用换用gh-proxy.com或直接 GitHub Releases。第四步创建 Bundle 结构并签名CCD 使用 macOS app bundle 格式二进制必须放在claude.app/Contents/MacOS/claude路径下。从 GitHub 镜像下载的二进制带有不匹配的代码签名必须用 ad-hoc 重新签名才能通过 macOS 的 Mach-O 头检查。VERSION2.1.187USER_DATA$HOME/Library/Application Support/Claude# 根据实际模式调整BASE$USER_DATA/claude-code/$VERSIONBUNDLE_BIN$BASE/claude.app/Contents/MacOS# 创建 bundle 结构mkdir-p$BUNDLE_BINcp$BASE/claude$BUNDLE_BIN/claudechmodx$BUNDLE_BIN/claude# Ad-hoc 重新签名解决 CODESIGNING SIGKILL 崩溃codesign--force--deep--sign-$BUNDLE_BIN/claude第五步写入 .verified 文件.verified文件必须包含 manifest 中platforms.darwin-arm64.bundle.checksum的值64 位十六进制 SHA256不能为空、不能有其他内容。# 从 manifest 获取的 bundle checksumecho2c83be71c9f40ed86a806574ae5ef3aa99aff9735a8aaec65922d495e1e148d7$BASE/.verified注意.verified文件中不能有换行符或多余空格。使用echo或printf直接写入。第六步验证修复# 验证二进制可执行$BUNDLE_BIN/claude--version# 期望输出: 2.1.187 (Claude Code)# 验证 Mach-O 头python3-c import struct with open($BUNDLE_BIN/claude, rb) as f: data f.read(8) magic_be int.from_bytes(data[0:4], big) magic_le int.from_bytes(data[0:4], little) cputype int.from_bytes(data[4:8], little) MH_MAGIC_64 0xFEEDFACF FAT_MAGIC 0xCAFEBABE CPU_ARM64 0x0100000C ok magic_be FAT_MAGIC or (magic_le MH_MAGIC_64 and cputype CPU_ARM64) print(fMach-O check: {\PASS\if ok else\FAIL\}) print(f FAT: {magic_be FAT_MAGIC}, Mach-O 64: {magic_le MH_MAGIC_64}, arm64: {cputype CPU_ARM64}) # 验证 .verified 内容xxd$BASE/.verified# 确保只有 64 字节十六进制串末尾是 0a (LF)不是 0d0a (CRLF)# 验证签名codesign-dvvv$BUNDLE_BIN/claude21|grepflags# 期望: flags0x2(adhoc)第七步重启 Claude Desktop# 强制关闭所有 Claude 进程pkill-9-fClaude2/dev/nullsleep2# 重新启动open/Applications/Claude.app启动后聊天窗口应不再显示 “Host Claude Code binary not available” 错误。CCD 内部验证链路了解 CCD 如何验证二进制有助于排查问题getBinaryPathIfReady() → getLocalBinaryPath() // 本地覆盖路径 → getHostPreseedInPlacePath() // app bundle 内预置 → binaryExistsForTarget() // ★ 正常路径 → getBinaryPathForTarget() → useBundletrue → storageDir/VERSION/claude.app/Contents/MacOS/claude → checks .verified 文件内容 manifest.platforms[platform].bundle.checksum → checkCachedBinaryHeader() (N4e) → Mach-O header 检查 → getAnyInstalledBinaryPathForTarget() // 回退到任意已安装版本常见问题Q: 二进制放在哪个目录取决于部署模式。通过进程--user-data-dir参数或deploymentModetelemetry 判断。模式userDatastorageDir1P~/Library/Application Support/Claude...Claude/claude-code3P~/Library/Application Support/Claude-3p...Claude-3p/claude-codeQ: 为什么二进制能执行但 Claude Desktop 仍报错可能是.verified文件内容不匹配必须用bundle.checksum非裸二进制checksum目录放在错误的 userData 下1P vs 3P代码签名被 macOS 阻止查看~/Library/Logs/DiagnosticReports/中的崩溃报告关键词CODESIGNINGMach-O header 检查失败二进制架构不匹配如 x64 vs arm64Q: Claude Desktop 版本升级后怎么办新版 Claude Desktop 可能变更requiredVersion→ 需要新版本二进制bundle.checksum→ 需要新的 .verified 值storageDir路径 → 可能变更升级后若再报错必须重新提取 app.asar 获取新 manifest重复第一步到第七步。Q: 3P 推理网关127.0.0.1:15721报 unhealthy这是独立问题不影响 CCD 二进制修复。确保 cc-switch 或其他 3P 推理服务正常运行。关键教训userData 路径因部署模式而异不要假设路径固定务必通过进程命令行确认版本号必须精确匹配manifest 中requiredVersion与二进制版本严格对照macOS 代码签名外部二进制必须 ad-hoc 重签才能通过 CODESIGNING 检查.verified必须用 bundle.checksum不是裸二进制 checksumapp.asar manifest 是唯一可靠来源硬编码版本号会随升级失效