One Person Lab Windows RC 安装与配置教程

Windows 11 x64 下载、校验、安装、Gateway 配置与 Docker WebUI

适用对象：希望在自己的 Windows 11 x64 电脑上试用 One Person Lab Desktop RC Preview 的用户。本教程不要求编程经验。

当前下载页面：https://github.com/gaofeng21cn/one-person-lab-app/releases/tag/windows-rc-26.7.30-rc.4

PDF 版本：下载本教程

本版本是供真实用户试用和反馈的 RC Preview，不是 Stable，也不会成为 GitHub Latest。它以专用 WSL 2 Linux 环境运行全部 Codex-backed 路径，但仍缺代码签名、 长周期升级和 Stable 渠道资格。不要在唯一保存重要工作的 电脑上把它当作正式稳定版替代品。

先了解这个 RC 的边界

One Person Lab 的 AionUI Shell 原本已经具备 Windows x64 打包、NSIS 安装器、 Windows 原生模块、AionCore 和 managed Codex ACP 资产。这个 RC 复用了这些成熟 的多平台打包能力。

这个 RC 的所有 Codex-backed 执行都进入 App 专用的 OPL-Linux WSL 2 环境， 包括 AionCore/ACP、Codex App Server 和 OPL Framework CLI。App 自动安装和修复 该发行版，并统一使用其中同一个 Linux Codex、CODEX_HOME 和工作区；不会静默 回退到原生 Windows AionCore、Codex 或 Framework。

WSL 2 是桌面 RC 的运行前提。首次启动时 App 会检查系统并创建或修复 OPL-Linux。只有 Windows 缺少必要功能时，系统才可能显示 UAC 并要求重启； 重启后再次打开 App 会继续配置。Windows Desktop App 不要求 Docker Desktop； Docker Desktop 只用于可选 WebUI 路径，桌面 RC 不会安装、修改或接管 Docker。

准备清单

安装前确认：

  • Windows 11 x64；不支持 32 位 Windows。
  • 至少 8 GB 内存，建议 16 GB 或更多。
  • 至少 15 GB 可用磁盘空间，用于 App、OPL-Linux、运行时、日志和项目缓存。
  • 可以访问 GitHub Releases 和所选模型服务的网络。
  • 一个单独的测试项目目录，不要直接用唯一的正式数据目录做首次试用。
  • 可选：Gateway 账户。账号、密码和 API Key 只在 App 的安全界面中输入。
  • Windows Update 没有等待完成的重启；WSL 2 可由 App 在首次启动时检查和启用。
  • 可选：Docker Desktop，用于浏览器 WebUI。

查看系统类型：

  1. 按 Win + I 打开“设置”。
  2. 进入“系统 -> 系统信息”。
  3. 确认“系统类型”包含“基于 x64 的处理器”。
  4. 确认 Windows Update 没有等待完成的重启。

1. 下载精确安装包

打开 RC Release 页面：

https://github.com/gaofeng21cn/one-person-lab-app/releases/tag/windows-rc-26.7.30-rc.4

在 Assets 中下载：

  • One-Person-Lab-26.7.30-rc.4-win-x64.exe
  • SHA256SUMS.txt
  • download-windows-preview.ps1

不要把 Source code ZIP/TAR 当成安装包。文件名中的 win-x64 表示 Windows x64， windows-rc-26.7.30-rc.4 表示当前公开候选预览，不是稳定更新频道。

建议在“下载”目录新建 OPL-RC 文件夹，把三个文件放在一起。

Windows 安装包包含首次配置所需的 Linux 运行时，当前安装包 约 330 MB。网络稳定时可以直接点击 EXE；浏览器可能先把页面导航 替换为后台下载，即使页面看起来没有变化，也先打开浏览器下载列表，确认是否出现 .crdownload 或正在下载的任务，不要重复点击多个下载。

弱网或经常断线时，优先只下载较小的 download-windows-preview.ps1 和 SHA256SUMS.txt。这个下载助手的文件名是 download-windows-preview.ps1；先在普通 PowerShell 验证助手本身：

cd "$HOME\Downloads\OPL-RC"
Get-FileHash -Algorithm SHA256 ".\download-windows-preview.ps1"
Select-String -Path ".\SHA256SUMS.txt" `
  -Pattern "download-windows-preview.ps1"

两处都应显示 ace814a06553acce4c85c26697de8415b15ef8d4127def1063db8752ed80449e。完全一致后运行：

powershell -ExecutionPolicy Bypass -File ".\download-windows-preview.ps1" `
  -ReleaseTag "windows-rc-26.7.30-rc.4" `
  -AssetName "One-Person-Lab-26.7.30-rc.4-win-x64.exe"

助手使用 Windows BITS 持久任务，显示已下载字节、总字节、百分比和任务状态。网络短暂 断开或关闭 PowerShell 后，再运行同一条命令会重新附着到同一个精确 Release、URL 和目标 路径，不会从零开始；helper 已在构建时绑定该 RC 的 tag、EXE 文件名、size 和 SHA-256， 不需要调用未认证 GitHub API。完成后会交叉核对内嵌摘要、SHA256SUMS.txt 和本地 SHA-256，完全一致才把临时文件原子改为最终 EXE 文件名。

浏览器直接下载会一直保留作为备用入口。项目不会自动切换到聊天群、网盘或任意第三方 镜像；以后只有项目 owner 公布、使用 HTTPS 且由同一不可变 Release 绑定相同 SHA-256 的 候选源，才有资格进入自动回退列表。

2. 校验 SHA-256

校验可以确认下载字节与 Release 公布的安装包一致。打开普通 PowerShell，不需要 管理员权限：

cd "$HOME\Downloads\OPL-RC"
Get-FileHash -Algorithm SHA256 ".\One-Person-Lab-26.7.30-rc.4-win-x64.exe"
Get-Content ".\SHA256SUMS.txt"

比较 Get-FileHash 输出和 SHA256SUMS.txt 中同名 EXE 的 64 位十六进制值：

  • 当前 RC4 EXE 的精确 SHA-256：40a356d70f488e1687c4786e8c41346f6fbb41333a8265c91eedaf975cbeaead。
  • 完全一致：继续安装。
  • 任意一位不同：删除 EXE，重新从同一个 RC Release 下载。
  • 文件名不同：不要猜测或改名，回到 Release 重新选择。

如果使用下载助手，也可以在下载完成后再次检查同一 SHA256SUMS.txt 中 download-windows-preview.ps1 的条目：

Get-FileHash -Algorithm SHA256 ".\download-windows-preview.ps1"
Select-String -Path ".\SHA256SUMS.txt" `
  -Pattern "download-windows-preview.ps1"

不要从聊天群、网盘、邮件附件或第三方镜像获取同名 EXE。哈希一致只证明字节 一致，不等于这个 RC 已完成正式代码签名。

3. 处理 Windows SmartScreen

当前 RC 可能尚未带正式 Authenticode 签名，因此 Windows SmartScreen 可能显示 “Windows 已保护你的电脑”。这是 Preview 已知限制，不应通过全局关闭安全功能来 绕过。

在已经确认 SHA-256 一致后：

  1. 双击 One-Person-Lab-26.7.30-rc.4-win-x64.exe。
  2. 若出现 Windows SmartScreen，先确认应用名称和下载文件名。
  3. 点击“更多信息”。
  4. 再点击“仍要运行”。

如果系统显示的文件名、发布者或路径与刚校验的文件不一致，立即取消。不要关闭 Microsoft Defender，也不要修改全局 SmartScreen 策略。

BITS 助手不会调用 Unblock-File、删除下载区域标记或绕过 SmartScreen。真正减少 SmartScreen 提示仍需要正式 Authenticode 签名和持续信誉积累；下载进度、断点续传和 SHA-256 校验只能让来源与字节状态更清楚，不能替代代码签名。

4. 安装 One Person Lab

安装器使用当前用户范围的交互式 NSIS 路径，通常不需要管理员权限。

  1. 在安装向导中点击“下一步”。
  2. 保留默认目录，或选择一个本机短路径目录。
  3. 保留“开始菜单快捷方式”。
  4. 需要时保留“桌面快捷方式”。
  5. 点击“安装”，等待文件复制完成。
  6. 勾选启动 One Person Lab，点击“完成”。

如果选择自定义路径，避免：

  • 网络共享或同步盘；
  • 含有非常长的多层目录；
  • 需要其他管理员账户才能写入的目录；
  • 旧 AionUI 或旧 OPL 测试目录。

首次启动比后续启动慢，因为 App 要检查 WSL 2、创建或修复专用的 OPL-Linux，并激活随包 Linux AionCore、managed Node、Codex ACP 和 OPL Framework。按界面中的配置进度等待；不要重复双击快捷方式。

如果首次配置遇到网络、代理或 VPN 短暂中断，窗口会保留错误原因并提供“重试”， 不会要求用户重新安装 App。只有 WSL 功能需要重启 Windows 时，才按窗口提示重启后继续。

若系统缺少 WSL 必要功能，Windows 可能显示一次 UAC：

  1. 确认请求来自 One Person Lab 后允许系统启用功能。
  2. 若 App 显示需要重启，保存其他工作并正常重启 Windows。
  3. 重启后从开始菜单再次打开 One Person Lab。
  4. App 会继续同一配置，不需要手工运行产品 bootstrap 命令。

5. 完成 Gateway 登录

首次进入后，App 会显示模型访问检查。默认使用 Gateway 账户：

  1. 打开“设置 -> 账户与访问”，或按首次设置提示进入。
  2. 选择 Gateway 账户。
  3. 在 App 界面输入邮箱和密码。
  4. 点击“登录并继续”。
  5. 登录成功后，确认 App 显示当前 Gateway 账户。
  6. 点击单独出现的“设为模型访问方式”。
  7. 等待模型访问检查完成。

密码、token 和 API Key 不应进入 PowerShell、命令行参数、日志、截图或问题 报告。登录只建立 Gateway 账户会话，不会代替第 6 步的模型访问确认；这项单独确认 用于避免 App 未经用户同意修改 Codex provider。需要兼容 API Key 时，也只在 App 的受控输入界面配置。

登录后打开“设置 -> 模型”，确认：

  • 模型目录可以读取；
  • Auto 或指定模型可选择；
  • 页面没有要求再次输入同一凭据；
  • 关闭再打开设置后，登录状态仍存在。

6. 做一次真实模型访问测试

在工作台创建一个测试任务，选择单独的测试目录。发送一个短且有明确返回标记的 请求，例如：

只回复 OPL_WINDOWS_RC_TEST_PASS，不要添加其他内容。

验收结果：

  • 回复准确出现 OPL_WINDOWS_RC_TEST_PASS；
  • 会话状态结束，不持续显示“正在运行”；
  • 模型和 reasoning 选择保持可见；
  • 关闭 App 后重新打开，同一登录和会话仍可读取。

不要把只打开窗口、只看到首页或只通过本地 health 当成模型访问成功。

7. 检查 WSL 2 状态

App 应自动维护专用的 OPL-Linux，且不修改你的其他发行版、默认发行版或 Docker Desktop 发行版。需要诊断时，可以在普通 PowerShell 查看只读状态：

wsl.exe --version
wsl.exe --status
wsl.exe --list --verbose

列表中应出现 OPL-Linux，VERSION 应为 2。不要手工进入发行版修改 /opt/opl、/home/opl/.codex 或 /home/opl/.opl；修复应由 App 完成。 不要运行 wsl.exe --unregister OPL-Linux 作为普通故障排除步骤，因为该命令会 不可恢复地删除发行版内的数据。

8. 可选：安装 Docker WebUI

浏览器 WebUI 是独立运行形态，适合服务器、隔离环境或希望在浏览器访问的用户。 完整教程：

https://gaofeng21cn.github.io/one-person-lab-app/latest/docker-webui-install/docker-webui-install.html

Windows 路径需要：

  • WSL 2 可用；
  • Docker Desktop 已安装；
  • Docker Desktop 使用 Linux containers；
  • Docker Engine 和 Compose 已 ready。

在普通 PowerShell 检查：

docker.exe version
docker.exe compose version
docker.exe context show

完成 WebUI 安装后访问：

http://localhost:3000/

首次登录仍只在浏览器界面输入 Gateway 账户。桌面 App 和 Docker WebUI 是两个 载体；不要假设它们自动共享所有本机数据目录。

如果 Docker Desktop 报错包含 dockerInference、AF_UNIX 或 “The file cannot be accessed by the system”，请使用上面的独立 Docker WebUI 教程。这个宿主 Docker 故障 与 Windows Desktop App 的内置运行时无关，不要为修复桌面 App 执行 Docker Factory Reset。

从本 RC 起，Windows Docker helper 在安装 Docker Desktop 后会重新读取持久化 Machine/User PATH，并优先使用绝对 docker.exe。这修复了同一 PowerShell 进程 PATH 仍旧、PATHEXT 缺少 .EXE 时错误报告“docker CLI was not found”的问题。

9. 重启与退出验证

完成一次真实请求后：

  1. 使用窗口右上角关闭 One Person Lab。
  2. 等待 10 秒。
  3. 从开始菜单重新打开。
  4. 确认 Gateway 登录仍有效。
  5. 打开上一条测试会话。
  6. 再发送一个短请求，确认模型访问仍成功。
  7. 再次正常退出。

如果任务管理器中长期残留多个 One Person Lab、Electron、AionCore 或 Codex 进程，记录时间和操作步骤后再报告。不要直接删除用户数据来掩盖退出问题。

10. 日志与问题报告

遇到问题时先记录：

  • Windows 版本和 OS build；
  • RC tag 与安装包文件名；
  • EXE SHA-256；
  • 安装阶段、首次启动阶段或模型请求阶段；
  • 可见错误文字；
  • WSL 2、Docker Desktop 是否启用；
  • 是否从旧测试版本升级。

默认用户数据和日志位于 Electron 的当前用户 App 数据目录，并有一部分受管运行 状态位于 OPL-Linux；具体路径以 App “设置 -> 日志与诊断”显示为准，通常在 %APPDATA% 下。问题报告前检查文件， 删除邮箱、项目内容、token、API Key 和其他秘密。

提交问题：

https://github.com/gaofeng21cn/one-person-lab-app/issues/new

不要上传整个用户数据目录。优先提供最小日志片段、截图、时间点和 SHA-256。

11. 检查更新

Windows RC Preview 不进入 Stable updater。App 中的“检查更新”可能只显示当前 稳定频道信息，不能用它判断是否有新的 Windows RC。

更新 Preview 时：

  1. 查看 One Person Lab App 的 GitHub Prereleases。
  2. 下载新的 win-x64.exe 与其 SHA256SUMS.txt。
  3. 再次校验 SHA-256。
  4. 正常退出旧 App。
  5. 运行新安装器并保留原安装目录。
  6. 启动后验证登录、会话和真实模型请求。

不要把新的 RC tag 改造成 v tag，也不要手工替换 updater metadata。

12. 卸载与用户数据

卸载 App：

  1. 正常退出 One Person Lab。
  2. 打开“设置 -> 应用 -> 已安装的应用”。
  3. 找到 One Person Lab。
  4. 点击“卸载”并完成向导。

卸载程序文件不等于删除用户数据、项目、Gateway 会话、OPL-Linux 或 Docker WebUI volume。 在确认备份和数据范围前，不要手工递归删除 %APPDATA%、项目目录、Docker volume 或 WSL 发行版。

需要彻底清理测试数据时，先从“设置 -> 数据与存储”和“日志与诊断”读取当前 目录，再逐项决定保留、导出或删除。不要执行全局 Docker prune 或注销 WSL 发行版来卸载桌面 App。

常见问题

双击后没有窗口

等待 20 秒并查看任务管理器。如果进程立即退出，记录日志路径和退出时间。不要 连续启动多个实例。

提示找不到 AionCore 或 Codex

RC4 每次启动都会检查 OPL-Linux 的 managed Node、运行入口和 Framework 身份。 如果只是上一次激活未完成或入口来自旧版本，App 会自动重新 bootstrap，然后再次 验证，不需要用户删除或注销 OPL-Linux。

如果界面显示“当前安装缺少必要的内置运行组件”或“托管 Node 运行环境无法启动”：

  1. 先点击“重启并重新检测”，只执行一次完整检查。
  2. 如果仍失败，记录界面列出的缺失组件，点击“打开日志目录”和“复制诊断”；复制的 诊断不应包含项目内容、凭据或任意用户文件。
  3. 检查 Windows 安全中心或杀毒软件的隔离记录。只有确认条目来自已经校验 SHA-256 的本 RC 安装目录时才恢复；不要关闭 Defender、添加整个磁盘排除项或修改全局 SmartScreen 策略。
  4. 如果安装目录中的内置文件已经被删除，正常退出 App，重新校验同一 windows-rc-26.7.30-rc.4 EXE，然后运行该安装器执行覆盖修复。不要删除用户数据、 Docker volume 或注销 WSL 发行版。
  5. 覆盖修复后再次打开 App；仍失败时使用界面的支持入口提交最小日志和复制诊断。

正式打包路径会物化 linux-x64 AionCore、managed Node、managed Codex ACP 和 OPL-Linux bootstrap；安装包中不应出现 win32-x64 executor。开发目录缺少这些 字节不等于安装包也缺失。

Docker 已安装但 PowerShell 找不到 docker

关闭当前 PowerShell，从开始菜单重新打开一个普通 PowerShell，再运行：

Get-Command docker.exe
Test-Path "$env:ProgramFiles\Docker\Docker\resources\bin\docker.exe"

本 RC 对应的 helper 已修复同进程 PATH/PATHEXT 状态转换。不要再次运行 Docker Desktop 安装器，先确认 canonical docker.exe 和 Docker Desktop daemon。

登录成功但模型不可用

先返回首次设置或打开“设置 -> 账户与访问”，检查是否仍显示“设为模型访问方式”。 若显示，点击该按钮并等待重新检测；再打开“设置 -> 模型”确认模型目录。只在 App 界面处理凭据，不要把 Gateway 密码放入问题报告。

是否可以用于正式生产

不建议。RC Preview 已执行 WSL2-only 自动 provisioning，但仍用于尽早发现 Windows 安装、路径、运行时和交互问题。正式 Windows 支持还需代码签名、长期 升级、正式安装器验收和 Stable 渠道资格。