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 SDKclaude可执行文件时,也会赋予这些可执行文件。只有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