跳转至

mac 签名(调试构建)

scripts/package-mac-app.sh 会构建一个暂存应用,调用 scripts/codesign-mac-app.sh,并在替换 dist/OpenClaw.app 之前验证已签名的运行时。macOS 将 TCC 权限与 bundle ID 和代码签名绑定。在重建过程中保持两者稳定,并将应用放在固定路径。这样 macOS 就会保留其 TCC 授权(通知、辅助功能、屏幕录制、麦克风、语音)。

  • 调试 bundle 标识符默认为 ai.openclaw.mac.debug(可通过 BUNDLE_ID=... 覆盖)。
  • 构建时 Node:>=24.16.0 <25 或 >=26.1.0(仓库 package.json 的 engines)。应用捆绑的是固定版本的 OpenClaw Bun 分支,而非 Node,同时还包括完整的 OpenClaw 包和 Control UI(pnpm ui:build)。
  • 默认情况下需要真实的签名身份。如果 codesign 脚本未找到身份且未设置 ALLOW_ADHOC_SIGNING,它会以错误退出。ad-hoc 签名(SIGN_IDENTITY="-")是显式选择启用的,并且不会在重建之间保留 TCC 权限。参见 macOS 权限。
  • 从环境中读取 SIGN_IDENTITY(例如 export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)",或 Developer ID Application 证书)。如果未设置,codesign-mac-app.sh 会自动选择一个身份。顺序为 Developer ID Application、Apple Distribution、Apple Development,然后是找到的第一个有效代码签名身份。
  • SIGN_IDENTITY 也接受证书 SHA-1 哈希,用于区分具有相同公用名的证书。
  • CODESIGN_TIMESTAMP=auto(默认)可为按名称或证书哈希选中的 Developer ID Application 签名启用可信时间戳。设置 on/off 可强制采用其中一种方式。
  • 在 Info.plist 中打上 OpenClawBuildTimestamp(ISO8601 UTC)、OpenClawGitCommit 和 OpenClawRuntimeBuildID 戳记。提交值是完整的 40 位十六进制提交哈希;对于本地构建,如果不可用则为 unknown。原生 关于 标签页会显示构建时间戳和 git 提交。私有运行时的包元数据必须在启动前与应用版本、提交、时间戳和运行时构建 ID 匹配。
  • 在签名后审计原生签名格式和 Team ID。默认情况下,元数据失败、非原生签名、缺少 Team ID 以及 Team ID 不匹配都会导致失败。SKIP_TEAM_ID_CHECK=1 仅跳过 Team ID 比较;原生签名格式检查仍会运行。
  • 在密封应用之前,对私有运行时的原生代码进行签名。JIT 内存授权(com.apple.security.cs.allow-jit 和 com.apple.security.cs.allow-unsigned-executable-memory)仅赋予 runtime/bin/bun;当捆绑插件包含 Claude Agent SDK claude 可执行文件时,也会赋予这些可执行文件。只有 runtime/bin/bun 还会额外获得 com.apple.security.cs.disable-library-validation。签名器会以普通签名方式处理其他原生辅助程序、.node 模块和库,包括 runtime/lib/libsqlite3.dylib。所有捆绑的原生代码都使用应用的签名身份。捆绑的 Anthropic 插件使用单独安装的 Claude Code 可执行文件。打包过程会在临时状态下,对每个可执行的架构在签名前后验证原生能力和 worker 就绪状态;当 Rosetta 不可用时,它会报告跳过 x86_64 验证。

私有 Bun 运行时可以加载运行时安装的 npm 插件中的原生模块(native addons),这些模块的二进制文件并非由应用的 Team ID 签名。对此可执行文件禁用库验证,与官方 Node 和 Bun macOS 二进制文件以及外部 Gateway 之前的 Node 运行时保持一致。该运行时本就会执行任意插件 JavaScript 并派生进程,因此库验证对它来说并非有意义的安全边界。捆绑的原生代码仍由 Team 签名,应用的各可执行文件、Claude SDK CLI 和其他辅助程序则保留库验证。此例外不会改变应用的开发覆盖(development override),也不会改变 Cloud Worker 对该覆盖的拒绝。

签名过程使用 /usr/bin/python3 扫描文件头,并通过 /usr/bin/file 批量处理候选文件。随后 Apple 的 /usr/bin/otool 会检查每个架构的原生头,包括 file 报告为数据的 fat64 容器。混合的签名类别和格式错误(malformed)的原生头会中止签名。Java 类、静态归档以及 Mach-O 链接器、调试和核心产物会被资源密封(resource-sealed),而非直接签名。发现过程会打开目录但不跟随符号链接,并对已打开的文件描述符进行分类,而不是对可重定向的路径进行分类。它不会运行捆绑的 Bun 来对自身进行签名。在发布前,扫描会检查每个观察到的输入,包括目录命名空间和未列入原生列表的资源;它会拒绝不完整的遍历和观察到的更改。这不是原子文件系统快照。

签名审计还要求具备原生 Mach-O 签名。某些 Apple 工具链在将原始 fat64 作为通用数据进行签名时会返回成功,但不包含原生授权。审计会拒绝该结果。签名器不会对输入容器进行 thin 处理或转换。对于不受支持的原生负载,请在打包前将其重建为与 codesign 兼容的代码,而不是依赖通用签名验证。

签名器会在 App 和 Sparkle bundle 所有者的嵌套代码之后,对它们各密封一次。对 bundle 主可执行文件的单独签名也会重新密封该 bundle 的资源。签名器密封应用后,新的清单会馈入 Team ID 与提权(elevation)审计。扫描器或分类器失败会中止签名。运行时可移植性检查会检查每个原生架构,并拒绝不可移植的依赖项以及损坏或逃逸的符号链接。

请对私有暂存副本进行签名,确保没有其他进程修改它。在属性清理之前,签名器会拒绝硬链接文件和特殊文件(如 FIFO)。如果此检查失败,请复制或重建 bundle。属性清理和签名使用 macOS 的 /usr/bin/sandbox-exec。它会将文件系统写入限制为固定的应用目录和临时签名目录。额外的继承文件描述符会被关闭。如果此变更边界无法启动,签名将失败。没有不受限制的回退。

使用

# from repo root
scripts/package-mac-app.sh                                                      # auto-selects identity; errors if none found
SIGN_IDENTITY="Developer ID Application: Your Name" scripts/package-mac-app.sh   # real cert
ALLOW_ADHOC_SIGNING=1 scripts/package-mac-app.sh                                 # ad-hoc (permissions will not stick)
SIGN_IDENTITY="-" scripts/package-mac-app.sh                                     # explicit ad-hoc (same caveat)
DISABLE_LIBRARY_VALIDATION=1 scripts/package-mac-app.sh                          # dev-only Sparkle Team ID mismatch workaround

运行时打包会遵循现有的 OPENCLAW_DOCKER_PACKAGE_INVENTORY_TIMEOUT_MS、 OPENCLAW_DOCKER_PACKAGE_PACK_TIMEOUT_MS 和 OPENCLAW_DOCKER_PACKAGE_TARBALL_CHECK_TIMEOUT_MS 预算。清单检查和 tarball 检查默认为五分钟;打包创建默认为十五分钟。 当打包需要更多时间时,请设置一个以毫秒为单位的正整数。 这些预算通过运行时的隔离环境传递,而不会暴露 操作员凭据或状态。tarball 检查预算覆盖整个检查过程, 包括解包和验证。

DISABLE_LIBRARY_VALIDATION=1 开发覆盖项适用于应用的 Sparkle 变通方案,而不是其私有运行时。OpenClawCloudWorker.app 会完全 拒绝该覆盖项;其提权宿主应用可执行文件始终保留 库验证。私有 Bun 运行时的插件加载例外 独立于该开发标志生效。

临时签名说明

SIGN_IDENTITY="-" 会禁用 Hardened Runtime(--options runtime)。这可防止应用在加载未共享相同 Team ID 的嵌入式框架(例如 Sparkle)时崩溃。临时签名还会破坏 TCC 权限持久性。有关恢复步骤,请参阅 macOS 权限。

关于页构建元数据

选择 关于 OpenClaw 可在原生连接窗口中选择 关于。它会显示来自 Info.plist 的应用版本和构建号、构建日期以及缩短的 git 提交,即使没有 Gateway 连接也是如此。将鼠标悬停在提交或日期上可查看完整值,或选择 复制构建信息 以复制所有构建元数据。缺失或无效的时间戳和提交值会显示为不可用。代码更改后重新运行打包器以刷新这些值。应用更新控件位于 仪表盘 → 设置 → 更新 → 此 Mac 下。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw