OpenCore 1.0.8 引导配置 · Intel i5-12400F · NVIDIA RTX 4060（NullMoth Metal 驱动）
已通过官方 ocvalidate 1.0.8 校验：No issues found.
这是一份经过逐项审计的 OpenCore EFI。所有配置项都能在官方 Configuration.tex 中找到依据，没有来路不明的键，也没有靠「抄别人的 EFI」堆出来的参数。
⚠️ 先读这一段
这个仓库里的 SMBIOS 三码是占位符，直接拿来用是启动不了的。
<string>MLB-GOES-HERE</string>
<string>SERIAL-GOES-HERE</string>
<string>UUID-GOES-HERE</string>
<data>AAAAAAAA</data>
请用 GenSMBIOS 为机型 MacPro7,1 生成你自己的三码，填进 EFI/OC/config.plist 的 PlatformInfo → Generic：
| 字段 | 怎么填 |
|---|
SystemProductName | 保持 MacPro7,1 |
SystemSerialNumber | GenSMBIOS 生成的 Serial |
MLB | GenSMBIOS 生成的 MLB |
SystemUUID | GenSMBIOS 生成的 SmUUID |
ROM | 你网卡的 MAC 地址（6 字节），GenSMBIOS 会自动生成 |
为什么不直接放作者的：公开发布真实三码会让别人也能用同一个身份登录 iMessage / FaceTime，最终导致该序列号被 Apple 拉黑，对谁都没好处。
硬件
| 部件 | 型号 | 状态 |
|---|
| 主板 | ASUS TX GAMING B760M WIFI D4 | ✅ |
| CPU | Intel Core i5-12400F (Alder Lake, 6P/12T) | ✅ 需 CPUFriend |
| 核显 | 无（F 后缀无 iGPU） | — |
| 独显 | NVIDIA GeForce RTX 4060（Ada 架构） | ⚠️ 第三方 Metal 驱动，装于 /Library/Extensions |
| 有线网卡 | Realtek RTL8125 2.5GbE | ✅ RTL812xLucy |
| 无线网卡 | Intel Wi-Fi 6 AX201 | ✅ AirportItlwm + OCLP-Mod |
| 蓝牙 | Intel 蓝牙（AX201 集成） | ✅ IntelBluetoothFirmware |
| 声卡 | Realtek ALC897 | ✅ layout-id = 77 |
| 存储 | NVMe SSD | ✅ NVMeFix |
软件版本
| 组件 | 版本 |
|---|
| EFI 版本 | v1.0.1（2026-10-22） |
| OpenCore | 1.0.8（x64，PE Machine 0x8664） |
| 显卡驱动 | NullMoth nvidia-macos-driver（Metal 翻译层，Turing+） |
| 目标系统 | macOS 26 Tahoe（本配置按 Ventura 版 AirportItlwm + OCLP-Mod 根补丁适配） |
| Lilu | 1.7.3 |
| VirtualSMC | 1.3.9（含 SMCProcessor / SMCSuperIO） |
| WhateverGreen | 1.7.2 |
| AppleALC | 1.9.9 |
| RestrictEvents | 1.1.7 |
| CPUFriend + DataProvider | 1.3.1 / 1.0.1 |
| NVMeFix | 1.1.4 |
| AMFIPass | 1.4.1 |
| AirportItlwm | 2.3.0（Ventura 构建） |
| IntelBluetoothFirmware / BTPatcher | 2.5.0 |
| BlueToolFixup | 2.6.9 |
| USBToolBox + UTBMap | 1.2.0 / 1.1 |
| RTL812xLucy | 1.1.1 |
目录结构
EFI/
├── BOOT/
│ └── BOOTx64.efi
└── OC/
├── ACPI/ 6 个 SSDT
│ ├── SSDT-EC.aml 嵌入式控制器（必须）
│ ├── SSDT-PLUG-ALT.aml CPU 电源管理（12 代必需）
│ ├── SSDT-USBX.aml USB 供电属性
│ ├── SSDT-USB-Reset.aml USB 复位
│ ├── SSDT-RTCAWAC.aml RTC 唤醒修复
│ └── SSDT-SBUS.aml SBUS 设备
├── Drivers/ 5 个 UEFI 驱动
│ ├── HfsPlus.efi 读 HFS+ 分区
│ ├── apfs_aligned.efi APFS 驱动（文件保险箱解锁）
│ ├── OpenRuntime.efi 运行时服务（必须）
│ ├── ResetNvramEntry.efi 开机菜单里的重置 NVRAM 项
│ └── OpenCanopy.efi 图形化启动菜单
├── Kexts/ 22 个启用的 kext
├── Resources/ GoldenGate 主题（26 个图标）
├── Tools/ OpenShell.efi
└── config.plist
安装
- 准备一个 ≥ 200 MB 的 FAT32 U 盘（或直接用你的 ESP 分区）。
- 把本仓库的
EFI/ 整个复制到 U 盘根目录，形成 U盘/EFI/BOOT/BOOTx64.efi 这样的结构。注意是复制 EFI 这一层，不要变成 EFI/EFI/BOOT。
- 填好你的三码（见开头警告）。
- BIOS 设置：
Secure Boot → DisabledFast Boot → DisabledVT-d → Disabled（或保持开启 + 依赖 DisableIoMapper）Above 4G Decoding → EnabledRe-Size BAR Support → Enabled（与 ResizeGpuBars 配合）CFG-Lock → Disabled（若找不到此项，配置里已开 AppleXcpmCfgLock 兜底）SATA Mode → AHCI
- 从 U 盘启动，进 macOS 安装器。
配置要点：为什么是这么写的
1. SecureBootModel = Disabled 与 FixupAppleEfiImages
这两个是一对，缺一不可。
官方 Configuration.tex 对 FixupAppleEfiImages 的原话：
On a system with such a modern, stricter loader this quirk is required to load Mac OS X 10.4 to macOS 10.12, and is required for all newer macOS when SecureBootModel is set to Disabled.
macOS 的 boot.efi 本身带有 W^X 权限错误，严格的 PE 加载器会拒绝加载。本配置因为要配合 OCLP-Mod 根补丁，SecureBootModel 必须是 Disabled，所以 FixupAppleEfiImages 必须 为 true。
很多从别处下载的 EFI 缺这个键（ocvalidate 会报 Missing key），因为它的 Failsafe 是 false，缺了就等同于关着 —— 平时能启动，遇到严格固件就卡住。
2. 显卡：NullMoth NVIDIA Driver
NVIDIA 没有为近年的 macOS 提供官方驱动（Web Driver 时代早已终结）。这台机器用的是
nullmoth/nvidia-macos-driver —— 一个把 Apple Metal 指令实时翻译成 Vulkan 的第三方 Metal 驱动。
Metal App → NVMTLDriver.bundle → 翻译器 (AIR → SPIR-V) → NVK (Mesa Vulkan) → NVRM / NVAccel / NVRMFB → GPU
| 组件 | 落盘位置 | 作用 |
|---|
NVMTLDriver.bundle | /Library/GPUBundles/ | Metal 驱动插件 |
libnvmtl_translate.dylib | 插件内部 | 着色器翻译（基于 metal2vulkan，LGPL-3.0） |
nvk/ | /Library/GPUBundles/nvmtl/ | Vulkan 后端（Mesa + NAK 编译器） |
NVRM NVAccel NVRMFB NVRMAGDC | /Library/Extensions/ | 内核扩展：驱动本体 / 加速器 / 显示 framebuffer / 显示策略 shim |
| GSP 固件 | /Users/Shared/nvfw/nvidia/… | NVIDIA 原厂固件 |
支持范围：Turing 及更新架构 —— GTX 16 系、RTX 20 / 30 / 40 / 50、TITAN RTX、Quadro RTX、T 系列。
本机是 Ada 架构的 RTX 4060，属于官方设备表覆盖范围。作者主要在 RTX 5060 上测试，其他型号可能存在尚未发现的问题。
关键：这些 kext 绝对不要在 EFI/OC/Kexts 里注入。
它们从 Auxiliary Kernel Collection 加载，OpenCore 只负责设置 SIP 和 boot-args。
本仓库的 config.plist 里因此没有任何 NVIDIA 相关条目 —— 这是正确的，不是漏配。
驱动对 OpenCore 的要求（本配置逐条核对）
| 要求 | 本配置 | 结果 |
|---|
boot-args 含 nvfb=1 nvaccel=1 nvfbheads=4 -nvkmsnosmooth amfi_get_out_of_my_way=0x1 amfi=0x80 ipc_control_port_options=0 | 全部存在 | ✅ |
不能有 nv_disable=1、-wegnoegpu（两者都会把 NVIDIA 卡藏起来） | 均无 | ✅ |
csr-active-config 包含 0x0A43 位 | 0x0FFF（超集，含该位） | ✅ |
Misc > Security > SecureBootModel = Disabled | Disabled | ✅ |
Lilu.kext 与 AMFIPass.kext 在 Kernel > Add 且启用 | 都在 | ✅ |
Kernel > Block 屏蔽 com.apple.iokit.IONDRVSupport | 已屏蔽 | ✅ |
不能有该卡的 WhateverGreen NVIDIA patch、不能有 agdpmod=pikera | 均无 | ✅ |
设进 NVRAM 的键必须同步写进 NVRAM > Delete | boot-args、csr-active-config 都在 | ✅ |
| 机型须能被该 macOS 版本接受 | MacPro7,1 —— 1401 从 1.14 起对带独显的台式机就是选它，macOS 15 与 26 都接受（iMacPro1,1 会被 macOS 26 拒绝） | ✅ |
| BIOS：Above 4G Decoding ON、CSM OFF | 见上方「安装」章节第 4 步 | — |
为什么 SecureBootModel 必须是 Disabled：Apple Secure Boot 会拒绝 Apple 未签名的 kext，而 NVRM 系列正是未签名加载的。
这同时解释了 §1 里 FixupAppleEfiImages 为什么在这里是强制项 —— 两者是同一条因果链上的上下游。
安装
推荐用作者配套的 1401 应用（nullmoth/1401）：它会自动定位启动用的 OpenCore 分区、备份 config.plist、写入上面这些设置、安装驱动，并在启动菜单里加一条 1401: Remove NVIDIA driver 用于一键还原。
手动安装则要 install.sh + 重建 Auxiliary Kernel Collection，且必须自己改对 OpenCore 配置 —— 顺序错了就是黑屏。
首次以驱动启动时，会停在 PCI configuration end 最多约一分钟等 GPU 起来，这是正常现象，不要以为卡死了。
gfxrst=4 到底是干什么的
不是显卡复位。 官方说明是：装了 WhateverGreen 的情况下，WhateverGreen 的启动画面拷贝会在 NVIDIA 显示打开时读取已释放的内存，导致 panic；gfxrst=4 就是消掉这个冲突的。
所以它跟显卡无关，跟 WhateverGreen 有关 —— 本机为 Intel 平台保留了 WEG，所以需要它。
排障用 boot-args（平时不要加）
| 参数 | 作用 |
|---|
-nvrmnoflip | 关闭零拷贝扫描输出，桌面闪烁 / 移动光标时撕裂优先试这个 |
-nvrmnopm | 关闭系统睡眠支持，症状是「睡眠后唤醒显卡回不来」 |
-nvrmnogo | 驱动先不自启，等 nvrmctl go 手动放行 |
-nvrmnobootscreen | 不截取启动画面 |
3. Kernel > Block 的三条屏蔽
| 被屏蔽的 kext | 原因 |
|---|
com.apple.iokit.IOSkywalkFamily | 用仓库里的改版替换，不屏蔽的话系统原版会抢先加载，Intel 网卡起不来 |
com.apple.driver.AppleEthernetRL | 系统自带 RTL 驱动与本机的 RTL812xLucy 冲突 |
com.apple.iokit.IONDRVSupport | 不屏蔽的话，固件自带的 framebuffer 会从 NVRMFB 手里抢走 display index 0，NVIDIA 输出起不来 |
4. Wi-Fi 的三段式依赖
Intel 网卡在 macOS 14+ 上不是只放一个 AirportItlwm 就够：
IOSkywalkFamily.kext ← 网卡协议栈基座（Apple 原版，需屏蔽系统同名 kext）
IO80211FamilyLegacy.kext ← 老版 802.11 框架
└── AirPortBrcmNIC.kext ← 它的插件，名字带 Brcm 但 Intel 也靠它挂载
AirportItlwm-Ventura.kext ← 真正的 Intel 驱动（Ventura 构建）
这三个 Apple 原版文件不是「Broadcom 专用、装在 Intel 机上白装」。凡是看到这种说法，都是误判。
为什么用 Ventura 构建 的 AirportItlwm：Tahoe 上的社区方案就是 Ventura 构建 + OCLP-Mod 根补丁，Sequoia 构建在 Tahoe 上不工作。
5. boot-args 逐条
keepsyms=1 amfi_get_out_of_my_way=0x1 amfi=0x80 ipc_control_port_options=0
nvfb=1 nvaccel=1 nvfbheads=4 -nvkmsnosmooth -lilubetaall gfxrst=4
| 参数 | 作用 |
|---|
keepsyms=1 | 内核崩溃时保留函数符号，否则 panic 日志全是裸地址。不要删 |
amfi_get_out_of_my_way=0x1 amfi=0x80 | 关闭 AMFI 校验，配合 AMFIPass + 根补丁 |
ipc_control_port_options=0 | 修复部分 App 的 XPC 通信 |
nvfb=1 nvaccel=1 nvfbheads=4 | NullMoth 驱动的必需项：启用 framebuffer、启用 NVAccel 加速、4 个显示头 |
-nvkmsnosmooth | 同上（驱动必需），关闭 nvkms 平滑缩放 |
-lilubetaall | 允许 Lilu 及其插件在较新的系统版本上加载 |
gfxrst=4 | 装了 WhateverGreen 时必需：否则 WEG 的启动画面拷贝会在 NVIDIA 显示打开时读已释放内存，直接 panic |
6. 日志已关闭
Misc > Debug > Target 设为 0。官方定义：0x01 位是总开关，关掉后「all log is discarded」，ESP 分区根目录不会再生成 opencore-*.txt；AppleDebug、ApplePanic、DisableWatchDog 一并置 false。
需要抓日志排查时：
<key>Target</key><integer>67</integer>
<key>AppleDebug</key><true/>
<key>ApplePanic</key><true/>
再在 boot-args 前面加回 debug=0x100。
7. 其他关键项
| 键 | 值 | 说明 |
|---|
Misc > Security > ScanPolicy | 0 | 不限制扫描范围，方便从任意分区启动 |
Misc > Security > Vault | Optional | 不做文件保管库校验 |
csr-active-config | 0x0FFF | SIP 基本全关，根补丁需要 |
DeviceProperties | layout-id = 77 | ALC897 的可用 layout |
PlatformInfo > UpdateSMBIOSMode | Custom | 配合 SpoofVendor = true |
UEFI > Output > Resolution | Max | 用显示器原生分辨率 |
Misc > Boot > PickerVariant | Acidanthera\GoldenGate | 图形化选单主题 |
这台机器上做过什么修复
本 EFI 经过完整审计，修掉了以下问题（记录见 commit 历史）：
| 问题 | 处理 |
|---|
SSDT-USBX.aml 在配置里 Enabled=true 但文件不存在 | 补回文件，USB 供电属性恢复注入 |
FixupAppleEfiImages 缺失（SecureBootModel=Disabled 下的必需项） | 补为 true |
15 处 schema 缺键，ocvalidate 报 16 项 | 全部补齐，校验清零 |
Misc > Debug 开着文件日志（Target=67） | 关闭 |
| 一个未被引用的孤儿 kext（15.4 MB） | 从仓库剔除 |
| 升级 macOS 26 后开机弹文件保险箱，正确密码也无法解锁 | 换用显式 apfs_aligned.efi，关闭 EnableJumpstart |
已知限制
- 显卡驱动是第三方逆向工程产物。 驱动的 kext 装在
/Library/Extensions 并从 Auxiliary Kernel Collection 加载，macOS 每次大版本升级都可能需要等驱动跟进新版本。升级系统前务必先看 releases 和 CHANGELOG。
- 显卡只支持 Turing 及更新架构。 Pascal、Maxwell 等更老的卡不在支持范围内。
- Wi-Fi 需要根补丁。 同上，
AirportItlwm 装进 /Library/Extensions 后依赖 OCLP-Mod 补丁链。
i5-12400F 无核显，无法使用 Sidecar / 随航的硬件编码，也无法在无独显时启动 GUI。- 不保证移植到其他主板可用。 ACPI 中的
SSDT-RTCAWAC、SSDT-SBUS 是针对这块板子生成的；换主板请重新生成。
- macOS 大版本升级前请先备份 EFI，并确认 kext 已跟进。
常见安装问题排查
第一件事永远是：用最新版的 1401 和驱动。下面很多问题在后续版本里已经修掉了，而用旧版 1401 做的 U 盘会一直带着旧问题，除非重做一次。
A. 卡在选单 / 还进不了 macOS
| 现象 | 原因 | 处理 |
|---|
停在 PCI configuration | 通常是 Resizable BAR 或 Above 4G Decoding 的设置 | BIOS 里打开 Above 4G Decoding、关掉 CSM。仍卡住就导出 U 盘日志 |
EB.MM.AKM、STOP 0x16、StartImage failed - Aborted、Couldn't allocate runtime area | 固件内存映射没给 boot.efi 留出空间（Ryzen 7000/9000 上常见） | 用最新 1401 重做 U 盘 —— 它会套用正确的内存设置，一组失败会自动换下一组。重启旧 U 盘没用 |
停在 EXITBS:START | macOS 已从固件接管，但在打印任何东西之前就停了。Intel 12 代及更新、AMD 笔记本上多为 CPU 核心布局或内存映射问题 | 先用最新 1401；再导出 U 盘的 opencore-*.txt；若出现 panic，在啰嗦模式下把整屏拍下来 |
This version of Mac OS X is not supported on this platform! 加一串 Mac-… 代码 | 配置里的机型不是这个 macOS 版本接受的机型。macOS 26 会拒绝 iMacPro1,1，macOS 15 拒绝一批更老的机型 | 用 MacPro7,1 —— 1401 从 1.14 起对带独显的台式机就是选它，macOS 15 和 26 都接受。本仓库正是 MacPro7,1 |
| 安装进度到约 19 分钟时整个冻住（Caps Lock 都不亮），Ryzen 7000/8000/9000 | 这些主板在安装器写固件设置时会挂住 | 重做 U 盘（1.14 已修）。自己维护 EFI 的话设 Booter > Quirks > DisableVariableWrite = true |
OCB: LoadImage failed - Unsupported、Failed to retrieve boot file from DMG | U 盘上的恢复镜像损坏 | 换一个 U 盘重做（1.14 写完会回读校验） |
OS.dmg.root_hash … Err(0xE) | 旧版 1401 做的 U 盘，或恢复镜像与目标 macOS 版本不匹配 | 用最新 1401 重做 |
| 选完 U 盘后偶尔卡住，重做一次又好了 | U 盘或接口在读那 900 MB 恢复镜像时太慢/不稳 | 换机箱后面的 USB 口，或换 U 盘 |
B. 驱动装好之后的显示问题
| 现象 | 原因 | 处理 |
|---|
| 桌面正常显示约 1 分钟后黑屏，只剩光标 | 启动约 1 分钟后驱动切到「从显卡显存直接扫描输出」（NVAccel::autoGo）。如果桌面其实画在集成显卡上、或显卡的 BAR 只有 256 MB 小窗口，这个画面就是空的 | 1.14 已修（这类机器上驱动会保持拷贝路径）。旧版加 -nvrmnoflip |
| 100–240 Hz 下黑屏或闪烁，或改分辨率/刷新率后出现 | 超过 DisplayPort 1.4 带宽的高刷模式需要 DSC 压缩，而 macOS 没被告知 | 1.14 会下发压缩设置。仍复现就在故障发生时按 Send logs，应用会记录显示路径 |
| macOS 26 (Tahoe) 下桌面全黑 | 包里 macOS 26 版的加速器（NVAccel）过期了 | 1.14 已修 |
| 显示器切到别的输入再切回来就没画面 | 驱动只点亮「没见过的新显示器」 | 1.14 已修。旧版把线拔了重插 |
无 Resizable BAR 的老 Intel 板上约 100 秒后黑屏，日志里是 cannot hold … not placing | 固件没有列出 64 位 PCI 地址范围，显卡的显存窗口无处安放 | 1.14 已修 |
| 显示器进入睡眠后，屏幕仍停留在最后一张画面上（不熄灭） | 驱动没有关掉显示输出 | 1.14 已修 |
睡眠后屏幕黑掉、机器必须硬复位（Sleep Wake Failure、Darkwake Exit Failure） | 驱动没有挂起/恢复 GPU，唤醒时把画面推到一块已经断电的卡上 | 新版已支持系统睡眠（见驱动仓库 docs/SLEEP-WAKE.md）。旧版先把系统睡眠关掉：sudo pmset -a sleep 0，也不要用苹果菜单里的「睡眠」 |
| 唤醒后桌面黑屏只剩光标，或停在睡前那张画面上 | WindowServer 没被告知 framebuffer 已经唤醒，或它的显存被替换掉了 | 新版已修。仍复现就发日志，里面有 NVRM-xnu: wake # 和 NVRM-fb: system wake |
睡眠中大约每分钟自己醒一次（pmset -g log 里 DarkWake ... due to XDCI ... XHCI） | 固件允许 USB 设备唤醒系统（GPE 0x6D）。这不是驱动的问题 | 用 SSDT-GPRW 在 ACPI > Patch 里把 GPRW 重命名为 XPRW，之后只有电源键能唤醒 |
| 窗口变黑块或停留在旧画面，点一下才刷新；预览里图片显示成马赛克 | 图像内容在 GPU 画完之前就被标记成「已是最新」 | 1.14 已修（社区补丁） |
| 浏览器报「Your browser does not support WebGL」 | 部分 WebGL 着色器翻译失败 | 1.14 已修 |
照片 App 人脸识别反复崩溃（mediaanalysisd） | 驱动里有一个 Metal 对象被释放了两次 | 1.14 已修 |
登录界面出现那一刻内核 panic（WindowServer、IOFramebuffer::postOpen、memcpy 缺页），且装了 WhateverGreen | WhateverGreen 在第一次 framebuffer 启动时，会从它开机时记下的地址拷贝启动画面；而 macOS 可能已经把那段映射释放了 | boot-args 加 gfxrst=4 —— 它关掉这次拷贝，改由驱动自己画启动画面。本仓库已包含 |
在 Turing（GTX 16 / RTX 20）上装完驱动后卡在 AppleKeyStore 循环 | 显卡固件需要更多时间，驱动才去点屏 | 1.13 起 Setup 会自动加 nvrmsettle=10000。手动装的自己加进 boot-args |
C. 出问题了怎么退回去（最重要的一段）
驱动出问题时可能连画面都没有，先记住这三条逃生路线，按严重程度递进：
1. 只想这一次不加载驱动
开机在 OpenCore 选单里选 1401: Start once without NVIDIA driver，按 Y，再选 macOS 或 Recovery。下次开机会自动恢复驱动。
2. 要彻底卸载驱动
选单里选 1401: Remove NVIDIA driver，按 Y，再选 macOS。它会自己卸载并重启，同时把保存的分辨率和刷新率恢复成安全默认值 —— 这样即使之前设过集成显卡显示不了的模式，也仍能看到画面。
3. 连选单和画面都看不见了
进 macOS Recovery（驱动在 Recovery 里不运行），打开「终端」执行：
nvram 7C436110-AB2A-4BBB-A880-FE41995C9F82:nullmoth-remove=1
然后重启进 macOS。机器会自己把驱动卸掉再重启一次，全程不需要画面。效果与选单里的卸载项完全一致。
选单里看不到那两个 1401 条目？
官方说明：安装器会把选单切成 Builtin、并且不再把条目藏在空格键后面。
本仓库的 Misc > Boot 当前是：
HideAuxiliary = false ✅ 条目不需要按空格才出现PickerMode = External（OpenCanopy 图形选单）⚠️ 与官方默认的 Builtin 不同
如果你的显示出了问题、而选单里又找不到那两个条目，会非常被动。 届时把 PickerMode 临时改成 Builtin 就能看到并选择它们，处理完再改回 External。这是本仓库相对官方默认配置唯一需要留意的地方。
另注：早期版本会往 OpenCore 里加一个 NullMothLogo.efi 启动项，现已废弃；新版安装/更新/卸载驱动时会自动移除它的条目和文件。若你的选单从来不出现，而 EFI 里还留着这个条目，就把它禁用掉。本仓库已不含任何 NullMothLogo.efi 条目。
D. 确认驱动到底有没有加载
重启后跑这两条：
kmutil showloaded --list-only | grep nullmoth
system_profiler SPDisplaysDataType | head -20
第一条应该输出 4 行，对应 NVRM / NVAccel / NVRMFB / NVRMAGDC 四个 kext。 第二条应该能看到你的 GeForce 显卡，并且 Metal: supported。
只满足一半（kext 加载了但 Metal 不支持）通常意味着 NVAccel 没有为该 macOS 版本正确编译或安装。
E. 拿日志
上面的表覆盖不到时，不要自己猜：
- Mac 端：1401 → Crash report → Send logs
- Windows 端 1401：Scan for logs and send them
它会带上驱动状态（PCI 设备 ID、BAR 地址）、内核日志、插件日志、崩溃报告和 OpenCore 启动日志，并自动去掉机器名、序列号和内存地址，最后给一个 report ID。把 report ID 贴进 issue，比贴手机拍的屏幕清楚得多。
F. 从 macOS 15 升级到 26 后，开机出现「文件保险箱」，正确密码也解不开
症状：升级完重启，macOS 启动前弹出一个解锁窗（文件保险箱 / FileVault），输入正确的账户密码提示密码错误，反复输也没用。
成因：macOS 26 的升级过程会把文件保险箱重新打开。开启之后，解锁发生在内核加载之前的预启动环境里 —— 这个界面由 Apple 自己的代码绘制，OpenCore 只负责递两样东西过去：APFS 驱动、键盘事件。所以密码校验完全在 Apple 手里，一旦 APFS 驱动和卷的加密元数据版本对不上，校验就会失败，表现和"输错密码"一模一样。
原配置依赖 UEFI > APFS > EnableJumpstart，它的作用是从 APFS 容器里自动抽取内嵌的签名驱动。升级后容器里可能同时存在新旧两套 Preboot，一旦抽到旧驱动，就读不懂新卷的加密元数据。
处理（v1.0.1 已内置）：
| 项目 | 值 |
|---|
OC/Drivers/apfs_aligned.efi | 新增，718,340 字节，sha256 1663fa54… |
UEFI > APFS > EnableJumpstart | true → false |
UEFI > Drivers | 新增 apfs_aligned.efi 条目，Enabled=true、LoadEarly=false |
关掉 Jumpstart 之后，APFS 驱动由固定文件提供，不再有"抽到哪个版本"的随机性。官方文档对该键的原文是 Load embedded APFS drivers from APFS containers —— 既然已有显式驱动，它就是冗余的。
MinVersion / MinDate 只作用于 Jumpstart 加载的驱动，关掉后这两个键失效。
改完第一次开机先确认一件事：OpenCore 选单里你的 macOS 卷还在。如果卷直接不见了，说明驱动没加载成功，立刻按 C 节回滚。
如果驱动正常、密码仍然解不开，问题就在卷的加密状态。进 Recovery（Recovery 分区不受文件保险箱保护，不需要密码），打开终端：
diskutil apfs list # 看 Locked 状态，确认没有升级残留的旧卷
diskutil apfs unlockVolume diskXsY # 交互输密码，报错比图形界面明确
diskutil apfs updatePreboot diskXsY # 解锁成功后立刻执行，重建 Preboot
能进系统之后，如果不需要文件保险箱，建议在「系统设置 → 隐私与安全性 → 文件保险箱」里关掉，免得下次大版本升级再踩一次。关之前先把数据备份好。
版权与归属
OpenCore.efi、OpenRuntime.efi、OpenCanopy.efi、ResetNvramEntry.efi、HfsPlus.efi 来自 Acidanthera OpenCore 与 OcBinaryData，遵循 BSD-3-Clause。- 各第三方 kext 版权归其作者所有，遵循各自的 LICENSE（Lilu / VirtualSMC / WhateverGreen / AppleALC / RestrictEvents / CPUFriend / NVMeFix 为 BSD-3；AirportItlwm / IntelBluetoothFirmware 为 GPL-2.0；USBToolBox 为 MIT）。
IOSkywalkFamily.kext、IO80211FamilyLegacy.kext、AirPortBrcmNIC.kext 是 Apple 原始二进制文件，版权归 Apple Inc. 所有，此处仅作互操作性研究用途。若权利人提出异议，将立即移除这些文件。- 本仓库不包含 nullmoth/nvidia-macos-driver 的任何文件。该项目的 kext 与插件以 PolyForm Noncommercial 1.0.0 授权（© NullMoth Systems），允许个人、研究、教育与非营利使用，禁止任何商业用途；其翻译器部分为 LGPL-3.0-or-later，NVK 部分为 Mesa 的 MIT 授权，GSP 固件遵循 NVIDIA 的可再分发固件许可。下载与安装请走官方 Releases。
config.plist 与文档由本仓库维护者整理，可自由参考。
免责声明
修改引导配置有风险，可能导致系统无法启动、数据丢失或硬件异常。使用前请备份重要数据。本仓库按「现状」提供，不附带任何担保，使用后果由使用者自行承担。
参考
关于本文档
本安装说明由 AI 生成，仅供参考。
文中内容取自 OpenCore 官方文档、ocvalidate 的实际输出、以及对本机 config.plist 的逐项比对。但硬件组合、驱动版本与系统行为都会随上游项目更新而变化 —— 动手前请核对各项目的官方文档并做好备份，不要仅凭本文操作。
OpenCore 1.0.8 boot configuration · Intel i5-12400F · NVIDIA RTX 4060 (NullMoth Metal driver)
Verified with the official ocvalidate 1.0.8: No issues found.
This is an OpenCore EFI that has been audited item by item. Every setting can be traced back to the official Configuration.tex — no mystery keys, no parameters copied from someone else's EFI without checking why they exist.
⚠️ Read this first
The SMBIOS values in this repository are placeholders. It will not boot as-is.
<string>MLB-GOES-HERE</string>
<string>SERIAL-GOES-HERE</string>
<string>UUID-GOES-HERE</string>
<data>AAAAAAAA</data>
Use GenSMBIOS to generate your own values for the model MacPro7,1, then put them into EFI/OC/config.plist under PlatformInfo → Generic:
| Field | What to put there |
|---|
SystemProductName | leave as MacPro7,1 |
SystemSerialNumber | the Serial generated by GenSMBIOS |
MLB | the MLB generated by GenSMBIOS |
SystemUUID | the SmUUID generated by GenSMBIOS |
ROM | your NIC's MAC address (6 bytes); GenSMBIOS generates this for you |
Why not ship the author's real values: publishing a real set of identifiers lets anyone sign into iMessage / FaceTime with the same identity, which eventually gets the serial blacklisted by Apple. Nobody wins.
Hardware
| Part | Model | Status |
|---|
| Motherboard | ASUS TX GAMING B760M WIFI D4 | ✅ |
| CPU | Intel Core i5-12400F (Alder Lake, 6P/12T) | ✅ needs CPUFriend |
| iGPU | none (the F suffix has no iGPU) | — |
| dGPU | NVIDIA GeForce RTX 4060 (Ada) | ⚠️ third-party Metal driver, installed to /Library/Extensions |
| Ethernet | Realtek RTL8125 2.5GbE | ✅ RTL812xLucy |
| Wi-Fi | Intel Wi-Fi 6 AX201 | ✅ AirportItlwm + OCLP-Mod |
| Bluetooth | Intel Bluetooth (built into AX201) | ✅ IntelBluetoothFirmware |
| Audio | Realtek ALC897 | ✅ layout-id = 77 |
| Storage | NVMe SSD | ✅ NVMeFix |
Software versions
| Component | Version |
|---|
| EFI version | v1.0.1 (2026-10-22) |
| OpenCore | 1.0.8 (x64, PE Machine 0x8664) |
| GPU driver | NullMoth nvidia-macos-driver (Metal translation layer, Turing+) |
| Target OS | macOS 26 Tahoe (this config targets the Ventura build of AirportItlwm plus the OCLP-Mod root patch) |
| Lilu | 1.7.3 |
| VirtualSMC | 1.3.9 (with SMCProcessor / SMCSuperIO) |
| WhateverGreen | 1.7.2 |
| AppleALC | 1.9.9 |
| RestrictEvents | 1.1.7 |
| CPUFriend + DataProvider | 1.3.1 / 1.0.1 |
| NVMeFix | 1.1.4 |
| AMFIPass | 1.4.1 |
| AirportItlwm | 2.3.0 (Ventura build) |
| IntelBluetoothFirmware / BTPatcher | 2.5.0 |
| BlueToolFixup | 2.6.9 |
| USBToolBox + UTBMap | 1.2.0 / 1.1 |
| RTL812xLucy | 1.1.1 |
Directory layout
EFI/
├── BOOT/
│ └── BOOTx64.efi
└── OC/
├── ACPI/ 6 SSDTs
│ ├── SSDT-EC.aml embedded controller (required)
│ ├── SSDT-PLUG-ALT.aml CPU power management (required on 12th gen)
│ ├── SSDT-USBX.aml USB power properties
│ ├── SSDT-USB-Reset.aml USB reset
│ ├── SSDT-RTCAWAC.aml RTC wake fix
│ └── SSDT-SBUS.aml SBUS device
├── Drivers/ 5 UEFI drivers
│ ├── HfsPlus.efi read HFS+ partitions
│ ├── apfs_aligned.efi APFS driver (FileVault unlock)
│ ├── OpenRuntime.efi runtime services (required)
│ ├── ResetNvramEntry.efi "Reset NVRAM" entry in the boot menu
│ └── OpenCanopy.efi graphical boot menu
├── Kexts/ 22 enabled kexts
├── Resources/ GoldenGate theme (26 icons)
├── Tools/ OpenShell.efi
└── config.plist
Installation
- Prepare a FAT32 USB stick of at least 200 MB (or use your ESP directly).
- Copy the whole
EFI/ folder from this repository to the root of the stick, so you end up with USB/EFI/BOOT/BOOTx64.efi.Copy the EFI level itself — do not end up with EFI/EFI/BOOT.
- Fill in your own SMBIOS values (see the warning at the top).
- BIOS settings:
Secure Boot → DisabledFast Boot → DisabledVT-d → Disabled (or leave it on and rely on DisableIoMapper)Above 4G Decoding → EnabledRe-Size BAR Support → Enabled (works together with ResizeGpuBars)CFG-Lock → Disabled (if the option does not exist, AppleXcpmCfgLock is already enabled as a fallback)SATA Mode → AHCI
- Boot from the stick and go into the macOS installer.
Configuration notes: why it is written this way
1. SecureBootModel = Disabled and FixupAppleEfiImages
These two go together. You need both.
What the official Configuration.tex says about FixupAppleEfiImages:
On a system with such a modern, stricter loader this quirk is required to load Mac OS X 10.4 to macOS 10.12, and is required for all newer macOS when SecureBootModel is set to Disabled.
macOS's boot.efi carries a W^X permission bug that strict PE loaders refuse to load. This configuration needs SecureBootModel = Disabled in order to use the OCLP-Mod root patch, so FixupAppleEfiImages must be true.
Plenty of EFIs downloaded from elsewhere are missing this key (ocvalidate reports Missing key). Its failsafe value is false, so a missing key is the same as having it off — it boots fine most of the time and hangs the moment you hit a strict firmware.
2. Graphics: NullMoth NVIDIA driver
NVIDIA does not provide drivers for recent macOS releases (the Web Driver era is long over). This machine uses
nullmoth/nvidia-macos-driver — a third-party Metal driver that translates Apple Metal commands into Vulkan at runtime.
Metal App → NVMTLDriver.bundle → translator (AIR → SPIR-V) → NVK (Mesa Vulkan) → NVRM / NVAccel / NVRMFB → GPU
| Component | Installed to | Role |
|---|
NVMTLDriver.bundle | /Library/GPUBundles/ | the Metal driver plug-in |
libnvmtl_translate.dylib | inside the plug-in | shader translation (based on metal2vulkan, LGPL-3.0) |
nvk/ | /Library/GPUBundles/nvmtl/ | Vulkan backend (Mesa + NAK compiler) |
NVRM NVAccel NVRMFB NVRMAGDC | /Library/Extensions/ | kernel extensions: driver core / accelerator / display framebuffer / display policy shim |
| GSP firmware | /Users/Shared/nvfw/nvidia/… | vendor firmware from NVIDIA |
Supported range: Turing and newer — GTX 16 series, RTX 20 / 30 / 40 / 50, TITAN RTX, Quadro RTX, T series.
This machine has an Ada-based RTX 4060, which is covered by the official device table. The author tests mainly on an RTX 5060, so other models may have undiscovered issues.
Key point: never inject these kexts through EFI/OC/Kexts.
They load from the Auxiliary Kernel Collection; OpenCore's only job is to set SIP and boot-args.
That is why this repository's config.plist contains no NVIDIA-related entries at all — that is correct, not a missing configuration.
What the driver requires from OpenCore (checked item by item here)
| Requirement | This configuration | Result |
|---|
boot-args contain nvfb=1 nvaccel=1 nvfbheads=4 -nvkmsnosmooth amfi_get_out_of_my_way=0x1 amfi=0x80 ipc_control_port_options=0 | all present | ✅ |
No nv_disable=1, no -wegnoegpu (both hide the NVIDIA card) | neither present | ✅ |
csr-active-config includes the 0x0A43 bits | 0x0FFF (superset, includes them) | ✅ |
Misc > Security > SecureBootModel = Disabled | Disabled | ✅ |
Lilu.kext and AMFIPass.kext in Kernel > Add and enabled | both present | ✅ |
Kernel > Block blocks com.apple.iokit.IONDRVSupport | blocked | ✅ |
No WhateverGreen NVIDIA patch for this card, no agdpmod=pikera | neither present | ✅ |
Keys written to NVRAM must also be listed in NVRAM > Delete | boot-args, csr-active-config both listed | ✅ |
| The model must be accepted by this macOS version | MacPro7,1 — 1401 has picked it for desktops with a dGPU since 1.14; accepted by both macOS 15 and 26 (iMacPro1,1 is rejected by macOS 26) | ✅ |
| BIOS: Above 4G Decoding ON, CSM OFF | see step 4 of "Installation" above | — |
Why SecureBootModel must be Disabled: Apple Secure Boot refuses kexts that Apple has not signed, and the NVRM family loads unsigned.
This is also why FixupAppleEfiImages in §1 is mandatory here — the two are upstream and downstream of the same causal chain.
Installing
Use the author's 1401 app (nullmoth/1401). It locates the OpenCore partition you boot from, backs up config.plist, writes the settings above, installs the driver, and adds a 1401: Remove NVIDIA driver entry to the boot menu for one-click rollback.
Installing manually means running install.sh, rebuilding the Auxiliary Kernel Collection, and getting the OpenCore configuration right by hand — get the order wrong and you get a black screen.
On the first boot with the driver, it can sit at PCI configuration end for up to about a minute while the GPU comes up. That is normal; do not assume it has hung.
What gfxrst=4 actually does
It is not a GPU reset. Per the official documentation: when WhateverGreen is installed, its boot-screen copy reads already-freed memory when the NVIDIA display is switched on, which panics. gfxrst=4 suppresses that conflict.
So it has nothing to do with the GPU and everything to do with WhateverGreen — this machine keeps WEG for the Intel platform, so the flag is needed.
Troubleshooting boot-args (do not add these normally)
| Flag | What it does |
|---|
-nvrmnoflip | disables zero-copy scanout; first thing to try for desktop flicker or tearing while moving the cursor |
-nvrmnopm | disables system sleep support; the symptom is "the GPU never comes back after sleep" |
-nvrmnogo | the driver does not start on its own; wait for a manual nvrmctl go |
-nvrmnobootscreen | does not capture the boot screen |
3. The three Kernel > Block entries
| Blocked kext | Why |
|---|
com.apple.iokit.IOSkywalkFamily | replaced by the patched build in this repo; without the block the stock version loads first and the Intel NIC never comes up |
com.apple.driver.AppleEthernetRL | the stock RTL driver conflicts with RTL812xLucy on this machine |
com.apple.iokit.IONDRVSupport | without the block, the firmware's own framebuffer takes display index 0 away from NVRMFB and the NVIDIA output never lights up |
4. The three-stage Wi-Fi dependency
On macOS 14+ an Intel card is not just a matter of dropping in AirportItlwm:
IOSkywalkFamily.kext ← base of the NIC protocol stack (Apple original, needs blocking the stock kext)
IO80211FamilyLegacy.kext ← the older 802.11 framework
└── AirPortBrcmNIC.kext ← its plug-in; "Brcm" in the name, but Intel cards mount through it too
AirportItlwm-Ventura.kext ← the actual Intel driver (Ventura build)
These three Apple originals are not "Broadcom-only, pointless on an Intel machine". Anyone saying so has it wrong.
Why the Ventura build of AirportItlwm: the community approach on Tahoe is the Ventura build plus the OCLP-Mod root patch; the Sequoia build does not work on Tahoe.
5. boot-args, one by one
keepsyms=1 amfi_get_out_of_my_way=0x1 amfi=0x80 ipc_control_port_options=0
nvfb=1 nvaccel=1 nvfbheads=4 -nvkmsnosmooth -lilubetaall gfxrst=4
| Flag | What it does |
|---|
keepsyms=1 | keeps function symbols in kernel panics; without it panic logs are bare addresses. Do not remove |
amfi_get_out_of_my_way=0x1 amfi=0x80 | disables AMFI validation, together with AMFIPass + the root patch |
ipc_control_port_options=0 | fixes XPC communication for some apps |
nvfb=1 nvaccel=1 nvfbheads=4 | required by the NullMoth driver: enable framebuffer, enable NVAccel acceleration, 4 display heads |
-nvkmsnosmooth | also required by the driver: disables nvkms smooth scaling |
-lilubetaall | lets Lilu and its plug-ins load on newer OS versions |
gfxrst=4 | required with WhateverGreen: otherwise WEG's boot-screen copy reads freed memory when the NVIDIA display comes up, straight to a panic |
6. Logging is off
Misc > Debug > Target is set to 0. Per the official definition, bit 0x01 is the master switch; with it off "all log is discarded" and no opencore-*.txt appears in the ESP root. AppleDebug, ApplePanic and DisableWatchDog are also false.
When you need logs for troubleshooting:
<key>Target</key><integer>67</integer>
<key>AppleDebug</key><true/>
<key>ApplePanic</key><true/>
Then add debug=0x100 back at the front of boot-args.
7. Other important keys
| Key | Value | Note |
|---|
Misc > Security > ScanPolicy | 0 | do not restrict scanning; boot from any partition |
Misc > Security > Vault | Optional | no vault validation |
csr-active-config | 0x0FFF | SIP essentially off, needed by the root patch |
DeviceProperties | layout-id = 77 | a working layout for ALC897 |
PlatformInfo > UpdateSMBIOSMode | Custom | pairs with SpoofVendor = true |
UEFI > Output > Resolution | Max | use the monitor's native resolution |
Misc > Boot > PickerVariant | Acidanthera\GoldenGate | graphical boot menu theme |
What has been fixed on this machine
This EFI has been fully audited; the following issues were fixed (see the commit history):
| Issue | Fix |
|---|
SSDT-USBX.aml was Enabled=true but the file did not exist | file restored; USB power properties are injected again |
FixupAppleEfiImages missing (required when SecureBootModel=Disabled) | set to true |
15 missing schema keys, ocvalidate reported 16 items | all filled in, validation now clean |
Misc > Debug had file logging on (Target=67) | turned off |
| one unreferenced orphan kext (15.4 MB) | removed from the repository |
| after upgrading to macOS 26, FileVault appears at boot and even the correct password is rejected | switched to an explicit apfs_aligned.efi, EnableJumpstart turned off |
Known limitations
- The GPU driver is a third-party reverse-engineering effort. Its kexts live in
/Library/Extensions and load from the Auxiliary Kernel Collection; every macOS major release may require waiting for the driver to catch up. Before upgrading, check the releases and CHANGELOG.
- Only Turing and newer GPUs are supported. Older cards such as Pascal and Maxwell are out of scope.
- Wi-Fi needs the root patch. Same story: once
AirportItlwm is installed to /Library/Extensions it depends on the OCLP-Mod patch chain.
- The
i5-12400F has no iGPU, so Sidecar hardware encoding is unavailable, and there is no GUI at all without the dGPU.
- Porting to another motherboard is not guaranteed.
SSDT-RTCAWAC and SSDT-SBUS in the ACPI folder were generated for this board specifically; regenerate them for a different one.
- Back up your EFI before any macOS major upgrade, and confirm the kexts have caught up.
Common installation problems
The first rule is always: use the latest 1401 and the latest driver. Many of the problems below were fixed in later versions, and a USB stick made with an older 1401 keeps its old problems until you rebuild it.
A. Stuck in the picker / cannot reach macOS yet
| Symptom | Cause | What to do |
|---|
Hangs at PCI configuration | usually Resizable BAR or Above 4G Decoding settings | Enable Above 4G Decoding and disable CSM in BIOS. If it still hangs, export the stick's log |
EB.MM.AKM, STOP 0x16, StartImage failed - Aborted, Couldn't allocate runtime area | the firmware memory map leaves no room for boot.efi (common on Ryzen 7000/9000) | rebuild the stick with the latest 1401 — it applies the right memory settings and falls through a list of them automatically. Rebooting the old stick will not help |
Hangs at EXITBS:START | macOS has taken over from the firmware but stops before printing anything. On Intel 12th gen and newer, and on AMD laptops, usually a CPU core layout or memory map problem | start with the latest 1401; then export the stick's opencore-*.txt; if there is a panic, photograph the whole screen in verbose mode |
This version of Mac OS X is not supported on this platform! followed by Mac-… codes | the configured model is not accepted by this macOS version. macOS 26 rejects iMacPro1,1; macOS 15 rejects a batch of older models | use MacPro7,1 — 1401 has picked it for desktops with a dGPU since 1.14, and both macOS 15 and 26 accept it. This repository ships MacPro7,1 |
| The installer freezes completely at around 19 minutes (even Caps Lock is dead), Ryzen 7000/8000/9000 | these boards hang while the installer writes firmware settings | rebuild the stick (fixed in 1.14). If you maintain your own EFI, set Booter > Quirks > DisableVariableWrite = true |
OCB: LoadImage failed - Unsupported, Failed to retrieve boot file from DMG | the recovery image on the stick is corrupt | use a different stick (1.14 reads back and verifies after writing) |
OS.dmg.root_hash … Err(0xE) | stick made with an old 1401, or the recovery image does not match the target macOS version | rebuild with the latest 1401 |
| Occasionally hangs after picking the stick, then works when rebuilt | the stick or port is too slow / unstable while reading that ~900 MB recovery image | use a rear USB port, or a different stick |
B. Display problems after the driver is installed
| Symptom | Cause | What to do |
|---|
| Desktop looks fine for about a minute, then goes black with only the cursor | about a minute after boot the driver switches to "scan out directly from VRAM" (NVAccel::autoGo). If the desktop is actually drawn on the iGPU, or the card's BAR is only a small 256 MB window, that surface is blank | fixed in 1.14 (the driver keeps the copy path on such machines). On older versions add -nvrmnoflip |
| Black screen or flicker at 100–240 Hz, or after changing resolution / refresh rate | high-refresh modes beyond DisplayPort 1.4 bandwidth need DSC compression, and macOS was never told | 1.14 sends the compression settings. If it still happens, hit Send logs while the fault is visible; the app records the display path |
| Completely black desktop on macOS 26 (Tahoe) | the accelerator (NVAccel) bundled for macOS 26 was outdated | fixed in 1.14 |
| No picture after switching the monitor to another input and back | the driver only lights up "displays it has not seen before" | fixed in 1.14. On older versions unplug and replug the cable |
Black screen after ~100 seconds on older Intel boards without Resizable BAR, log says cannot hold … not placing | the firmware does not list a 64-bit PCI address range, so there is nowhere to put the card's VRAM window | fixed in 1.14 |
| After the display sleeps, the screen stays on the last frame (never turns off) | the driver does not turn off the display output | fixed in 1.14 |
Screen goes black after sleep and the machine needs a hard reset (Sleep Wake Failure, Darkwake Exit Failure) | the driver did not suspend / resume the GPU and pushes the picture to a powered-down card on wake | newer builds support system sleep (see docs/SLEEP-WAKE.md in the driver repo). On older versions disable system sleep first: sudo pmset -a sleep 0, and avoid "Sleep" in the Apple menu |
| After wake the desktop is black with only the cursor, or stuck on the pre-sleep frame | WindowServer was not told the framebuffer woke up, or its VRAM was replaced | fixed in newer builds. If it still happens, send logs — they contain NVRM-xnu: wake # and NVRM-fb: system wake |
Wakes by itself roughly once a minute during sleep (pmset -g log shows DarkWake ... due to XDCI ... XHCI) | the firmware allows USB devices to wake the system (GPE 0x6D). This is not a driver problem | add SSDT-GPRW and rename GPRW to XPRW in ACPI > Patch; then only the power button wakes the machine |
| Windows turn into black blocks or keep an old frame until clicked; images look mosaic in Preview | image content is marked "up to date" before the GPU finishes drawing it | fixed in 1.14 (community patch) |
| Browser says "Your browser does not support WebGL" | some WebGL shader translations fail | fixed in 1.14 |
Photos app face recognition crashes repeatedly (mediaanalysisd) | a Metal object is released twice in the driver | fixed in 1.14 |
Kernel panic the moment the login window appears (WindowServer, IOFramebuffer::postOpen, memcpy page fault), with WhateverGreen installed | on the first framebuffer start, WhateverGreen copies the boot screen from an address it recorded at boot; macOS may already have unmapped it | add gfxrst=4 to boot-args — it disables that copy and lets the driver draw the boot screen itself. Already included here |
On Turing (GTX 16 / RTX 20) it hangs in an AppleKeyStore loop right after installing the driver | the GPU firmware needs more time before the driver lights up the display | since 1.13 Setup adds nvrmsettle=10000 automatically. Manual installs: add it to boot-args yourself |
C. How to roll back when something breaks (the most important section)
A bad driver can leave you with no picture at all. Remember these three escape routes, in order of severity:
1. Skip the driver for this one boot
In the OpenCore picker choose 1401: Start once without NVIDIA driver, press Y, then pick macOS or Recovery. The next boot restores the driver automatically.
2. Remove the driver completely
Choose 1401: Remove NVIDIA driver, press Y, then pick macOS. It uninstalls and reboots by itself, and resets the saved resolution and refresh rate to safe defaults — so even if you had set a mode the display cannot show, you still get a picture.
3. You cannot even see the picker
Boot into macOS Recovery (the driver does not run there), open Terminal and run:
nvram 7C436110-AB2A-4BBB-A880-FE41995C9F82:nullmoth-remove=1
Then reboot into macOS. The machine removes the driver itself and reboots once more, with no display needed at any point. The effect is identical to the uninstall entry in the picker.
Cannot find those two 1401 entries in the picker?
Per the official documentation, the installer switches the picker to Builtin and stops hiding the entries behind the space bar.
This repository's Misc > Boot currently is:
HideAuxiliary = false ✅ entries do not require pressing spacePickerMode = External (OpenCanopy graphical picker) ⚠️ differs from the official default of Builtin
If your display is broken and you cannot find those two entries, you are in a bad spot. In that case temporarily change PickerMode to Builtin so you can see and select them, then change it back to External afterwards. This is the only place this repository deviates from the official default configuration.
Also note: early versions added a NullMothLogo.efi boot entry to OpenCore; that is deprecated, and newer installers/updaters/uninstallers remove its entry and file automatically. If your picker never appears while that entry is still in the EFI, disable it. This repository contains no NullMothLogo.efi entry at all.
D. Verify whether the driver actually loaded
After rebooting run these two commands:
kmutil showloaded --list-only | grep nullmoth
system_profiler SPDisplaysDataType | head -20
The first should print 4 lines, for the NVRM / NVAccel / NVRMFB / NVRMAGDC kexts.
The second should show your GeForce card with Metal: supported.
Only half of that (kexts loaded but no Metal) usually means NVAccel was not correctly built or installed for that macOS version.
E. Getting logs
When the tables above do not cover it, do not guess:
- On the Mac: 1401 → Crash report → Send logs
- 1401 on Windows: Scan for logs and send them
It collects driver state (PCI device IDs, BAR addresses), kernel logs, plug-in logs, crash reports and the OpenCore boot log, strips machine names, serial numbers and memory addresses, and gives you a report ID. Paste that report ID into an issue — far more useful than a photo of the screen.
F. After upgrading from macOS 15 to 26, FileVault appears at boot and even the correct password is rejected
Symptom: after the upgrade, a password window (FileVault) appears before macOS starts. Entering the correct account password reports a wrong password, and repeated attempts do not help.
Cause: the macOS 26 upgrade turns FileVault back on. Once enabled, unlocking happens in the pre-boot environment before the kernel loads — that screen is drawn by Apple's own code; OpenCore only hands over two things: the APFS driver and keyboard events. So the password check is entirely Apple's, and if the APFS driver does not understand the volume's encryption metadata version, the check fails and looks exactly like "wrong password".
The original configuration relied on UEFI > APFS > EnableJumpstart, which automatically extracts the embedded signed driver from the APFS container. After an upgrade the container may hold both an old and a new Preboot; if the old driver gets picked, it cannot read the new volume's encryption metadata.
Fix (included since v1.0.1):
| Item | Value |
|---|
OC/Drivers/apfs_aligned.efi | added, 718,340 bytes, sha256 1663fa54… |
UEFI > APFS > EnableJumpstart | true → false |
UEFI > Drivers | new apfs_aligned.efi entry, Enabled=true, LoadEarly=false |
With Jumpstart off, the APFS driver comes from a fixed file, so there is no more randomness about which version gets picked. The official documentation describes the key as Load embedded APFS drivers from APFS containers — given an explicit driver, it is redundant.
MinVersion / MinDate only apply to drivers loaded by Jumpstart, so both keys stop having any effect once it is off.
Check one thing on the first boot after the change: your macOS volume is still in the OpenCore picker. If the volume is simply gone, the driver failed to load — roll back per section C immediately.
If the driver is fine and the password still does not work, the problem is the volume's encryption state. Boot into Recovery (the Recovery partition is not protected by FileVault, so no password is needed) and open Terminal:
diskutil apfs list # check Locked state, confirm there is no leftover volume from the upgrade
diskutil apfs unlockVolume diskXsY # interactive passphrase prompt; errors are clearer than the GUI
diskutil apfs updatePreboot diskXsY # run right after a successful unlock to rebuild Preboot
Once you can boot into macOS, if you do not need FileVault, turn it off in System Settings → Privacy & Security → FileVault so the next major upgrade does not hit this again. Back up your data before turning it off.
Copyright and attribution
OpenCore.efi, OpenRuntime.efi, OpenCanopy.efi, ResetNvramEntry.efi and HfsPlus.efi come from Acidanthera OpenCore and OcBinaryData, under BSD-3-Clause.- All third-party kexts are copyright their respective authors and follow their own licenses (Lilu / VirtualSMC / WhateverGreen / AppleALC / RestrictEvents / CPUFriend / NVMeFix are BSD-3; AirportItlwm / IntelBluetoothFirmware are GPL-2.0; USBToolBox is MIT).
IOSkywalkFamily.kext, IO80211FamilyLegacy.kext and AirPortBrcmNIC.kext are original Apple binaries, copyright Apple Inc., included solely for interoperability research. They will be removed immediately if the rights holder objects.- This repository contains no files from nullmoth/nvidia-macos-driver. That project's kexts and plug-ins are licensed under PolyForm Noncommercial 1.0.0 (© NullMoth Systems), which permits personal, research, educational and non-profit use and forbids any commercial use; its translator is LGPL-3.0-or-later, the NVK part is Mesa's MIT license, and the GSP firmware follows NVIDIA's redistributable firmware license. Download and install it from the official releases.
config.plist and the documentation were assembled by this repository's maintainer; feel free to use them as a reference.
Disclaimer
Changing boot configuration is risky: it can leave the system unbootable, cause data loss or hardware misbehaviour. Back up important data first. This repository is provided "as is", without any warranty; you are responsible for the consequences of using it.
References
About this document
This installation guide was generated by AI and is for reference only.
Its content is drawn from the official OpenCore documentation, actual ocvalidate output, and an item-by-item comparison against this machine's config.plist. Hardware combinations, driver versions and system behaviour all change as upstream projects evolve — check each project's official documentation and keep a backup before you start, and do not act on this document alone.