把 91MB 装进客户电脑：我们的端应用为什么这样长

先说清楚它是什么：一莲AI OpenClaw 是我们的端应用，定位是「本地智能体网关」——模型推理走云端，编排对话、读写文件、跑工具这些事留在客户自己的机器上。下面这些数字、机制和坑，全部来自我们自己的工程记录，没有一处是包装出来的形容词。

⁰¹它到底装了什么

下载下来是一个 91.2MB 的单文件 exe，没有别的安装依赖。点开之后，它在这台机器上落下的东西大致是这些：

装完占用的磁盘空间约 200MB，最低要求是 Windows 10 64 位、4GB 内存——推荐 8GB，因为 Node 进程加上界面壳并不轻。

⁰²为什么不干脆做个网页，非要塞到本地

这是我们被问得最多的问题，答案不是"本地更安全"这种口号，而是四条具体的、在真实客户场景里反复出现的原因。

• 要碰客户自己的文件和工具。一个只会聊天的窗口，网页做得更好；但客户要的是"帮我把这个 Excel 里的重复行清掉""把这批发票按日期归到文件夹"。浏览器给不了这个权限，本地进程可以。
• 不能假设网络一直好。网关、配置、技能缓存都在本地，网络抖动时界面不白屏、历史对话还在、装好的技能还能看见。
• Key 和对话不该默认上云。对话历史存在本机安装目录里，API Key 用 Windows DPAPI 加密，只有本机账户能解。这不是营销话术，是把"能不上传就不上传"写成了默认行为。
• 它得一直在。关掉窗口后最小化到系统托盘，网关继续跑；客户在手机上远程连回自己电脑时，靠的就是这个常驻进程。

代价也很直接：一个网页更新是推一次代码，一个端应用更新是每个客户都得升级一次。这就是为什么后面的版本与升级机制占了我们大量精力。

⁰³一次安装，其实分两段

很多"一键安装"是把所有活都堆给一个安装器，出了错只能报一句"安装失败"。我们把它拆成两段：安装器只负责放文件，业务初始化交给程序自己。

安装器是 Inno Setup 的标准五步——协议、安装位置、准备、安装、完成，用户熟悉这套流程；EULA 和路径都在这一层收口。第一次启动控制台时，才进入真正的初始化：

之所以敢这么拆，是因为下载环节做了多源断点续传：Node 走 nodejs.org 与 npmmirror 双源，OpenClaw 走 npmjs 与 npmmirror 双源，先 HEAD 诊断哪个源通，失败自动切换，文件大小不对判为异常重下。安装界面上有 5 阶段指示器、实时速度和剩余时间，以及一行"当前在干什么"的子任务状态——客户看到的不是转圈，而是"正在从镜像源校验包"。

安装体验的分水岭不在成功路径，而在失败路径：客户断网、镜像挂了、包下到一半——这三种情况我们都要让界面说清楚"卡在哪一步、下一步会自己重试"。

端应用安装流程的设计原则

⁰⁴双模式：省事和便宜，选一个

接入方式只有两种，差别不在功能，在钱和数据的路径：

托管模式下的"配额闸"放在本地反向代理这一层：请求还没离开这台机器，就先判断余额够不够、这个授权允许走哪个模型。余额不足时返回的是一句明确的"算力 Token 不足"，而不是一个 500 或者一段莫名其妙的截断。

⁰⁵三个真正吃掉时间的工程问题

功能列表写出来是一页纸，但下面这三件事各花掉我们不止一个版本的时间，而且都是"用户不说就发现不了"的类型。

长回复看起来卡死

症状是客户问一个需要长回答的问题，界面停在半空，等十几秒才一次性吐出来一大段。根因有两层：一是本地代理拿了全量响应再回吐，二是 LLM 请求的默认超时只有 30 秒，长回答直接被掐断。做法是把超时提到 900 秒，并把 SSE 改成边收边发、64KB 分块透传——流是流，不是攒完再放。非 LLM 的小接口维持原来的 30 秒，不让整条链路一起变慢。

每次安装都在重装核心

OpenClaw 的版本号输出带前缀和构建后缀（形如 OpenClaw 2026.7.1-2 (0790d9f)），和官方源里的纯版本号永远不相等——于是每次启动都判定"版本不一致"，重新装一遍核心，客户看到的就是装得慢、流量还大。修法是加一个版本规范化函数，剥掉前缀后缀再比较，同版本就正确跳过。

重装一次，就被当成新设备

一机一授权最怕误判。早期指纹里掺了 CPU 序列号和磁盘序列号，这两项通过 PowerShell 的 WMI 查询拿，偏偏在权限受限或超时的机器上会失败——同一台机器每次读到的值不一样，重装后被判成新设备，客户就得再买一份。现在只保留三个跨卸载重装稳定的因子：MAC、主机名、MachineGuid，再额外用 MAC 与 MachineGuid 的组合生成一个"机器锚点"上报，服务端据此把重装后的新指纹并回原授权。

设备指纹这个设计，出发点不该是"尽量多抓特征"，而是"抓到的特征必须每次都一样"。抓到会漂移的特征，等于给自己制造售后。

一次因为指纹漂移导致的重复购买投诉之后

⁰⁶加固做到什么程度，边界在哪里

端应用会被拆、会被看源码，这是默认前提。所以我们做的是提高成本，不是承诺不可破解：Python 侧的核心逻辑做混淆，产出 .obf 与 secure_info.json 随包分发；构建流水线里这一步和打包绑定，绕过它打出来的包会直接起不来。这挡得住随手改两行代码的人，挡不住愿意花几周的人。

另外三件与数据有关的事实，写在这里方便核对：

• 对话与日志默认只在本机。日志不自动上传，除非客户主动点"提交诊断报告"；卸载时本地数据一并删除。
• API Key 用 Windows DPAPI 加密。只有本机对应的账户能解密，配置文件被拷走也解不出明文。
• 升级不清数据。覆盖安装保留 config、logs、state 三处，客户的授权、历史对话和已装技能不会被一次升级抹掉。

⁰⁷版本这件事，我们做得很死板

端应用发布有个反复踩过的坑：同一个版本号发两次，客户的升级检测就乱了。现在的规则是每次打包自动递增，版本号只有一个真源，打包脚本先 bump 再走后续五步（生成裁剪版、生成版本资源、混淆、PyInstaller、Inno 打包），任何一步绕过都会导致状态不同步。

发布节奏上，控制台顶部出现新版本提示时可以一键升级；也可以不管它，托盘里的后台流程会挑空闲时更新。升级失败不会把原来的版本弄坏——旧版本的目录留在原地，下次启动仍然可用。