问题：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() → useBundle=true, platform=darwin-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-fix
description: “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: true

Claude Desktop CCD Binary Fix

概述

Claude Desktop 需要本地 Claude Code 二进制才能驱动对话功能。在国内环境下，downloads.claude.ai CDN 不可达导致自动下载失败，报错 “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.asar
npx asar extract /Applications/Claude.app/Contents/Resources/app.asar /tmp/claude-asar-extract

# 2. 提取 manifest（bft() 函数返回的 JSON）
python3 -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(r'function 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 模式（deploymentMode=1p）：~/Library/Application Support/Claude
• 3P 模式（deploymentMode=3p）：~/Library/Application Support/Claude-3p

判断方法：启动 Claude Desktop 后查看进程命令行：

ps aux | grep "/Applications/Claude.app/Contents/MacOS/Claude$" | grep -o 'user-data-dir=[^ ]*'
# 如果有 user-data-dir=.../Claude-3p → 3P 模式
# 如果没有 user-data-dir 参数 → 1P 模式（默认 Claude）

也可以从渲染进程的 telemetry 中查看：

ps aux | grep "Claude Helper (Renderer)" | grep -o 'deploymentMode":"[^"]*"' | head -1

第三步：下载 Claude Code 二进制

从 GitHub 镜像下载精确版本的二进制（国内直连 GitHub 可能失败，使用 ghfast.top 加速）：

VERSION="2.1.187"  # 从 manifest 获取
USER_DATA="$HOME/Library/Application Support/Claude"  # 1P 模式；3P 则为 Claude-3p
DST="$USER_DATA/claude-code/$VERSION"
mkdir -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 头检查。

VERSION="2.1.187"
USER_DATA="$HOME/Library/Application Support/Claude"  # 根据实际模式调整
BASE="$USER_DATA/claude-code/$VERSION"
BUNDLE_BIN="$BASE/claude.app/Contents/MacOS"

# 创建 bundle 结构
mkdir -p "$BUNDLE_BIN"
cp "$BASE/claude" "$BUNDLE_BIN/claude"
chmod +x "$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 checksum
echo "2c83be71c9f40ed86a806574ae5ef3aa99aff9735a8aaec65922d495e1e148d7" > "$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(f'Mach-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/claude" 2>&1 | grep 'flags'
# 期望: flags=0x2(adhoc)

第七步：重启 Claude Desktop

# 强制关闭所有 Claude 进程
pkill -9 -f "Claude" 2>/dev/null
sleep 2

# 重新启动
open /Applications/Claude.app

启动后，聊天窗口应不再显示 “Host Claude Code binary not available” 错误。

CCD 内部验证链路

了解 CCD 如何验证二进制有助于排查问题：

getBinaryPathIfReady()
  → getLocalBinaryPath()          // 本地覆盖路径
  → getHostPreseedInPlacePath()   // app bundle 内预置
  → binaryExistsForTarget()       // ★ 正常路径
    → getBinaryPathForTarget()
      → useBundle=true → storageDir/VERSION/claude.app/Contents/MacOS/claude
    → checks .verified 文件内容 == manifest.platforms[platform].bundle.checksum
    → checkCachedBinaryHeader() (N4e) → Mach-O header 检查
  → getAnyInstalledBinaryPathForTarget()  // 回退到任意已安装版本

常见问题

Q: 二进制放在哪个目录？

取决于部署模式。通过进程 --user-data-dir 参数或 deploymentMode telemetry 判断。

模式	userData	storageDir
1P	~/Library/Application Support/Claude	...Claude/claude-code
3P	~/Library/Application Support/Claude-3p	...Claude-3p/claude-code

Q: 为什么二进制能执行但 Claude Desktop 仍报错？

可能是：

1. .verified 文件内容不匹配（必须用 bundle.checksum，非裸二进制 checksum）
2. 目录放在错误的 userData 下（1P vs 3P）
3. 代码签名被 macOS 阻止（查看 ~/Library/Logs/DiagnosticReports/ 中的崩溃报告，关键词 CODESIGNING）
4. Mach-O header 检查失败（二进制架构不匹配，如 x64 vs arm64）

Q: 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：不是裸二进制 checksum
• app.asar manifest 是唯一可靠来源：硬编码版本号会随升级失效