本文目录
先按日志分清失败发生在哪一步
OpenClash 显示“内核不存在”或“内核更新失败”时，不要先重装插件。当前官方脚本依次读取远端版本、按已选 CPU 架构下载压缩包、检查 gzip、解压到临时文件、授予运行权限并执行 -v，全部通过后才替换正式内核。第一条明确错误决定下一步应该查什么。
Core Version Check Error 表示远端版本信息没有读到；Core Download Failed 表示压缩包请求失败；Core Verification Failed 表示下载内容未通过 gzip 检查。
Core Update Failed 表示解压、权限或 -v 自检失败；Core Move Failed 才是把已验证临时文件放到目标路径时失败。它们不是同一个问题。
截至 2026 年 9 月 13 日，OpenClash 最新稳定版仍是 v0.47.156。本文说明的是当前 master 更新脚本和这个稳定版可用的安全排查路径，不把单一 issue 中的路由器环境写成所有设备都会遇到的故障。
第一条错误对应的检查方向
| 日志或现象 | 失败阶段 | 优先检查 |
|---|---|---|
| Core Version Check Error | 版本元数据 | 系统时间、CA 证书、curl 与 GitHub 访问 |
| Core Download Failed | 压缩包下载 | 网络、下载超时与 GitHub 地址代理设置 |
| Core Verification Failed | 压缩包校验 | 是否下载到 HTML 错误页、截断文件或错误镜像 |
| Core Update Failed | 解压和执行自检 | CPU 架构、压缩格式、可执行权限与二进制是否完整 |
| Core Move Failed | 写入正式路径 | 可用空间、只读文件系统与目标目录 |
| No Compiled Version Selected | 架构未选择 | 版本更新页的编译版本选项 |
- 读取远端版本失败时记录 Core Version Check Error
- 下载架构包按 core_version 请求官方压缩包
- 验证并解压gzip、解包、权限与 -v 依次通过
- 移动到目标路径只有已验证的临时文件才能替换旧内核
- 重启并验证核对版本、启动日志和真实 HTTPS 请求
第一条失败日志对应哪一个检查点，就只修那一段；不要把下载、架构、空间和配置问题混在一起。
修复前先保留仍可运行的旧内核
如果 OpenClash 目前还能启动并转发流量，先不要删除 /etc/openclash/core，也不要连续点击更新。官方脚本把新文件写入带 .new 和进程号的临时路径，完成 gzip、解压、chmod 4755 与 -v 自检后才覆盖正式文件；自动更新失败时，旧内核通常仍是最可靠的回退点。
先在 OpenClash 状态页记录当前运行内核和版本，再按站内升级指南备份 UCI 设置、配置文件与覆写。内核文件只应作为同设备、同架构的短期回退副本，不能代替配置备份，也不要把包含订阅或密钥的整个目录公开上传。
建立可回退基线
停止重复更新
等待当前任务结束，只保留一次完整日志，避免多个下载与重启同时进行。
记录当前状态
记录 OpenClash 版本、运行内核、内核版本、已选编译架构和小闪存模式状态。
备份配置
导出当前可用配置与 OpenClash 设置；公开副本必须先脱敏。
验证旧内核
固定当前节点完成一次真实 HTTPS 请求，确认故障只发生在更新，不是现有转发已经中断。
核对 CPU 架构、目标路径、空间与时间
当前下载脚本直接读取 UCI 的 core_version，并把它拼入 clash-${core_version}.tar.gz。这里需要的是 OpenClash 版本更新页提供的编译架构，不是凭路由器商品名猜一个相近值。选错后即使下载完整，也可能在执行 -v 时失败。
Issue #4758 的日志同时出现下载超时和“只能在支持 v3 微架构的 AMD64 处理器上运行”。它只能证明那台设备至少存在网络与架构两条问题，不能证明所有手动上传失败都由 amd64-v3 引起。
当前官方编译流程中的 amd64 与 amd64-v3 都要求 GOAMD64 v3；x86_64 不等于 CPU 支持 v3。遇到 v3 unsupported 时应在更新页选择 amd64-compatible 或 amd64-v1，不能把 plain amd64 当兼容版。
普通模式的正式目标是 /etc/openclash/core/clash_meta；小闪存模式的自动更新目标改为 /tmp/etc/openclash/core/clash_meta。不要绕过界面把文件硬复制到猜测的目录。先核对设置，再检查对应挂载点与 /tmp 的可用空间。
uci -q get openclash.config.core_version
uci -q get openclash.config.small_flash_memory
df -h /etc/openclash /tmp
date检查结果怎么判断
| 结果 | 含义 | 处理 |
|---|---|---|
| core_version 为空或为 0 | 没有可下载的编译版本 | 回到版本更新页选择与设备匹配的架构 |
| 日志提示处理器不支持 | 二进制架构或微架构不匹配 | 恢复旧内核并重新选择较兼容的官方构建 |
| /etc 可用空间不足 | 正式文件可能无法移动 | 删除自己确认无用的包缓存或日志，不删除配置和旧内核 |
| 小闪存模式开启且 /tmp 不足 | RAM 目标无法容纳新内核 | 释放临时空间或重启后再试，不改自动目标路径 |
| 系统日期明显错误 | TLS 证书校验可能失败 | 先恢复 NTP 或手动校准时间，再重试官方地址 |
版本检查或 TLS 失败时先修系统条件
官方 v0.47.156 安装说明把 curl 与 ca-bundle 列为依赖。Issue #5114 的一台设备在下载 openclash_last_version 和 clash_last_version 时分别记录 curl 35 TLS connect error 与 curl 60 certificate has expired。
该 issue 是没有维护者根因结论的单机报告，只能说明版本文件也可能遇到 TLS 类错误；它不能证明内核压缩包缺失，也不能证明重装 ca-bundle 必然有效。
先确认路由器时间正确，再在软件包页面核对 curl 与 ca-bundle 已安装且没有损坏。不要给 curl 增加 -k，不要关闭 TLS 校验，也不要把版本地址改成 HTTP；这些做法会让内核更新失去来源校验边界。
若直连 GitHub 不稳定，可使用 OpenClash“覆写设置 > 常规设置”里的 GitHub 地址代理选项。当前脚本会根据该设置构造官方 OpenClash core 分支或受支持 CDN 的地址。只选择界面提供、自己信任的选项，不粘贴论坛中的未知镜像。
恢复版本与下载链路
校准系统时间
先让 NTP 成功同步，刷新页面后确认日期、时区和年份正确。
核对官方依赖
在 OpenWrt 软件包页面确认 curl 与 ca-bundle 已安装；不要混用来源不明的证书包。
单独重试一次
保存设置后只点击一次版本或内核检查，用新日志确认错误是否仍停在同一阶段。
必要时换官方代理选项
只在 OpenClash 自带 GitHub 地址代理设置中更换一次，再比较错误和下载进度。
用官方更新流程完成一次干净重试
架构、空间、时间与 CA 证书都正常后，回到 OpenClash 的版本更新页重新检查内核。当前脚本每次任务最多重试三次，并在每次尝试前清理本次下载文件与临时新内核；不要在它仍运行时再开第二个任务。
下载成功不代表更新完成。日志还应依次出现下载成功、开始更新和 Core Update Successful。若停在 Verification、Update 或 Move，继续按对应阶段处理，不要因为进度到过 100% 就判断内核已经替换。
更新成功后脚本才会安排重启。重启前不要改订阅、DNS 或防火墙，以免同时引入第二个变量。若插件仍使用旧版本，先完整刷新状态页并核对实际 -v 输出，不要重复覆盖。
官方重试成功的最小证据
- 本次日志只有一个内核更新任务，没有并发重试
- 下载内容通过 gzip 校验并完成解压
- 临时内核已通过 chmod 4755 与 -v 自检
- 日志出现 Core Update Successful，而不只是下载 100%
- 重启后状态页显示的内核版本已经变化
自动下载仍失败时安全手动上传
手动上传只解决路由器无法稳定下载官方文件，不会修复架构选错、空间不足或 TLS 来源不可信。先在另一台可信设备从 vernesong/OpenClash 的 core 分支取得与当前 release branch、Meta 类型和 core_version 完全一致的官方文件。
文件名应与自动脚本构造的 clash-${core_version}.tar.gz 对应。上传控件明确标注 [Meta] Core File (.tar.gz)；不要改名上传 ZIP、自制多文件包或把这一步套用到 Smart、Oix。
进入 OpenClash 的配置管理上传区，选择 [Meta] Core File (.tar.gz)。当前 config.lua 会在临时子目录解包，把第一个普通文件移动为 /etc/openclash/core/clash_meta，设置 4755 权限并清理上传临时目录。
这个手动入口不会执行 -v，也没有哈希或签名核验，还会直接替换旧文件。上传前必须另存可运行的旧内核；上传后的 File saved 只表示文件处理完成，不代表架构兼容或能够运行。
小闪存模式、定制固件或后续版本可能通过链接或运行目录处理内核，所以最终必须以当前界面的保存提示、状态页和 -v 输出为准。若上传后仍显示内核不存在，不要反复上传不同架构；回到前一节重新核对 core_version 和空间。
手动上传的安全顺序
确认精确架构
抄下版本更新页的 core_version，不用 CPU 品牌或商品型号代替。
备份工作内核
在上传前另存当前能运行的 clash_meta，确认副本来自同一设备和架构。
只取官方文件
从 OpenClash 官方 core 分支取得匹配架构、分支和 Meta 类型的单文件 .tar.gz，不使用第三方重打包。
通过配置管理上传
选择 [Meta] Core File (.tar.gz)，让当前插件负责解包、重命名和权限设置。
先自检再启动
确认状态页能读取内核版本，再启动 OpenClash；读不到版本时立即停下，不改防火墙。
更新后验证版本、启动与真实流量
上传成功提示只说明文件处理完成。先在状态页确认 Meta 内核文件存在、运行权限正常且能显示版本，再启动 OpenClash。若页面仍缓存旧结果，刷新后重新读取，不用再次上传来“碰碰运气”。
随后检查启动日志中的配置测试、内核启动和 DNS、防火墙步骤。最后固定一条已知可用节点，分别完成一个域名解析和一个真实 HTTPS 请求；如果内核能启动但业务失败，应转查配置、DNS、规则或节点，而不是继续更换二进制。
/etc/openclash/core/clash_meta -v完成修复前逐项确认
- 状态页的已选架构与下载文件完全一致
- 内核文件存在、权限正常并能输出版本
- 启动日志不再出现 Version、Download、Verification、Update 或 Move Failed
- 配置测试通过，OpenClash 服务保持运行
- 域名解析成功，真实 HTTPS 请求可完成
- 旧内核与配置备份仍保留在不公开的位置
仍失败就回退旧内核，不删除配置
如果新内核无法执行、启动后立即退出或使原本可用的配置失败，先停止 OpenClash，恢复修复前保存的同设备、同架构旧内核，再让插件读取版本并启动。不要把不兼容的新文件留在正式路径上反复重启，也不要同时降级插件、内核和配置。
自动更新在新文件通过自检前使用独立临时路径，因此下载、校验或解压失败时，最安全的动作通常是停止更新并继续使用旧内核。若旧内核已经被手动覆盖且没有备份，从官方 core 分支重新取得已知可用的同架构版本；不要从群聊或网盘找一个同名 clash_meta。
回退后再次做版本输出、启动日志、DNS 与 HTTPS 四项验证。只有旧内核恢复正常且新版本问题能稳定复现，才向 OpenClash issue 提交插件版本、core_version、第一条失败日志、剩余空间和脱敏环境信息。
旧内核恢复后正常
保持旧版本，等待官方修复或重新核对新文件架构，不再连续更新。
旧内核也无法执行
检查目标路径、权限、文件系统和备份是否来自同一架构。
内核启动但配置测试失败
转查 YAML 与内核字段兼容性，不再按下载故障处理。
服务启动但设备无法上网
恢复系统接管前的网络，再分流 DNS、防火墙、规则和节点。