remote-codex 0.11.44 → 0.11.49

package/docs/windows-device-manager.zh.md

@@ -0,0 +1,143 @@
+# Remote Codex Windows Device Manager
+
+`RemoteCodex.DeviceManager.exe` 是原生 Windows 11 x64 托盘应用。它把一台 Windows 电脑配置为 Remote Codex Relay Device，并在当前用户登录期间维持设备连接。
+
+## 用户侧安装
+
+目标电脑不需要预装 .NET、Node.js、npm、Remote Codex 或 Codex。准备以下内容即可：
+
+- Windows 11 x64；
+- 一个可以完成 Codex 浏览器登录的 Windows 用户；
+- Relay Portal 创建 Device 后只显示一次的 `rcd_...` token；
+- 可访问 `nodejs.org`、`chatgpt.com`、OpenAI release 域名、npm registry 和 Relay 域名的网络。
+
+运行 EXE 后会将自身复制到：
+
+```text
+%LOCALAPPDATA%\RemoteCodex\DeviceManager\RemoteCodex.DeviceManager.exe
+```
+
+随后首次配置窗口会要求：
+
+1. 确认 Relay URL；
+2. 输入 Device token；
+3. 选择 Workspace root；
+4. 确认本地端口，默认 `45680`；
+5. 选择是否随当前 Windows 用户登录启动；
+6. 点击 **Connect device**。
+
+第一次连接时，应用会依次：
+
+- 探测可用的 Windows x64 Node.js 22；
+- 缺少兼容 Node 时下载私有 Node.js `22.23.2` 并校验 SHA-256；
+- 探测 Codex，缺少时调用 OpenAI 官方 Windows installer；
+- 检查 `codex login status`，未登录时打开临时终端完成用户登录；
+- 在 `%LOCALAPPDATA%\RemoteCodex\app` 安装固定版本的私有 Remote Codex；
+- 通过现有 CLI 写 Relay 配置并收紧 `%USERPROFILE%\.remote-codex` ACL；
+- 启动后台 Relay Supervisor 并验证生命周期状态。
+
+托盘的 **Supervisor running** 表示本机 Supervisor 已经通过身份校验并保持 Relay 自动重连。Relay 服务端是否已接受当前 token，仍以 Relay Portal 的 **Online** 状态为最终依据；失效或已撤销的 token 不会被本地进程状态误称为 Online。
+
+已有的健康 Node.js 22 和 Codex 会直接复用。已有的其他 Node.js 大版本不会被卸载、覆盖或写入 PATH；应用会并存安装自己的 Node.js 22。私有 Remote Codex 第二次运行时会验证并跳过重复安装。
+
+## 托盘行为
+
+主窗口关闭或最小化后，应用只隐藏到通知区域，Device 继续运行。托盘菜单提供：
+
+- **Open**：打开配置和状态窗口；
+- **Connect / Disconnect**：连接或主动下线；
+- **Change device token...**：输入新 token，优雅重启并应用；
+- **Open Relay portal**；
+- **Open logs**；
+- **Start with Windows**：切换当前用户登录启动；
+- **Exit and take device offline**：停止 Supervisor 后退出托盘应用。
+
+应用每 10 秒检查一次 Supervisor。只要用户没有点 **Disconnect** 或退出应用，进程异常停止后会自动拉起。开机启动使用当前用户的 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`，不要求管理员权限，也不会把 Device token 写进启动参数。
+
+## 敏感数据与文件位置
+
+Device Manager 自身的 `settings.json` 不保存 Device token。Token 只交给 Remote Codex CLI，并由现有私有配置逻辑保存：
+
+```text
+%USERPROFILE%\.remote-codex\relay-supervisor.json
+```
+
+其他文件：
+
+```text
+%LOCALAPPDATA%\RemoteCodex\DeviceManager\settings.json
+%LOCALAPPDATA%\RemoteCodex\DeviceManager\runtime-state.json
+%LOCALAPPDATA%\RemoteCodex\runtime\
+%LOCALAPPDATA%\RemoteCodex\app\
+%LOCALAPPDATA%\RemoteCodex\logs\device-manager.log
+%USERPROFILE%\.remote-codex\logs\relay-supervisor.log
+```
+
+日志层会脱敏 `rcd_...`、token、password、secret、Authorization 和 `controlToken`。Codex 登录凭据仍由 Codex 自己管理；Device Manager 不读取或复制凭据内容。
+
+## 从源码构建
+
+开发机需要 .NET 8 SDK。Windows PowerShell 中运行：
+
+```powershell
+git switch codex/windows-device-manager
+./scripts/windows/build-device-manager.ps1
+```
+
+输出位于：
+
+```text
+artifacts\windows-device-manager\win-x64\RemoteCodex.DeviceManager.exe
+artifacts\windows-device-manager\win-x64\RemoteCodex.DeviceManager.exe.sha256
+```
+
+也可以直接执行：
+
+```powershell
+dotnet publish apps/windows-device-manager/RemoteCodex.DeviceManager.csproj `
+  -c Release `
+  -r win-x64 `
+  --self-contained true `
+  -p:PublishSingleFile=true `
+  -o artifacts/windows-device-manager/win-x64
+```
+
+自包含单文件约 150 MB，目标电脑不需要 .NET runtime。GitHub Actions 的 **Windows device manager** workflow 会在 `windows-2022` 构建、执行 EXE 自检、生成 SHA-256 并上传 `remote-codex-device-manager-win-x64` artifact。
+
+正式公开分发前应配置仓库 secrets：
+
+```text
+WINDOWS_SIGNING_CERTIFICATE_BASE64
+WINDOWS_SIGNING_CERTIFICATE_PASSWORD
+```
+
+CI 检测到证书后会进行 Authenticode SHA-256 签名、可信时间戳和签名验证。没有证书时仍会生成供开发测试的未签名 artifact，Windows 可能显示 SmartScreen 提示。
+
+## Windows 实机验收
+
+建议在 Windows Codex App 拉取分支后至少完成以下验证：
+
+1. 在没有 Node、Codex 和 .NET 的 Windows 11 x64 用户中运行 EXE；
+2. 输入真实 token，完成 Codex 登录，确认 Portal Device 变为 Online；
+3. 关闭主窗口，确认托盘图标仍存在且 Device 继续 Online；
+4. 在任务管理器结束 Relay Supervisor，确认托盘应用自动恢复；
+5. 从托盘更换 token，确认旧连接停止、新 Device Online；
+6. 退出托盘应用，确认 `relay-supervisor status` 为 stopped/offline；
+7. 重新运行两次，确认 Node、Codex 和 Remote Codex 均走复用/跳过路径；
+8. 启用 **Start with Windows** 后注销并登录，确认托盘和 Device 自动恢复；
+9. 在已有 Node 20 或 24 的电脑上运行，确认原 Node 和 PATH 没有被修改；
+10. 检查日志，确认没有完整 token、密码或 session secret。
+
+## 当前边界
+
+- 首版目标是 Windows 11 x64，不包含 ARM64；
+- Codex 账号登录必须由用户交互完成，应用不能代替用户认证；
+- Relay Device token 仍由用户从 Portal 输入，后续可升级为短时一次性 enrollment code；
+- 本地构建默认未签名，正式公开下载必须使用稳定发布者证书签名；
+- 卸载当前通过托盘退出后删除 `%LOCALAPPDATA%\RemoteCodex` 完成；`%USERPROFILE%\.remote-codex` 和 Codex 登录数据默认保留，避免误删 workspace、数据库或凭据。
+
+## 相关文档
+
+- [Windows Device 从零手工安装指南](windows-device-setup.zh.md)
+- [Windows 一键安装器调研](windows-one-click-installer-research.zh.md)
+- [Remote Codex 原生 Windows 支持](windows.md)

package/docs/windows-device-setup.zh.md

@@ -0,0 +1,263 @@
+# Windows Device 从零安装指南
+
+本文说明如何把一台没有开发环境的 Windows 电脑配置成 Remote Codex Relay Device。完成后，该电脑上的 Relay Supervisor 会主动连接公网 Relay，并允许已授权的 Web 或移动端访问这台电脑上的工作区和 Codex 会话。
+
+正式图形化入口已经实现，优先使用 [Remote Codex Windows Device Manager](windows-device-manager.zh.md)。它是自包含单文件 EXE，能够探测并补齐 Node.js、Codex 和 Remote Codex，提供托盘常驻、换 Token、自动重连和当前用户开机启动。本文保留手工 PowerShell 流程，供排障、审计和受管环境使用。
+
+## 1. 当前支持范围
+
+当前原生 Windows 首版支持范围为：
+
+- Windows 11 x64；
+- Node.js 22 LTS；
+- 原生 Codex provider，支持 `codex.exe` 和 npm 产生的 `codex.cmd`；
+- 当前用户主目录或其他本地磁盘上的工作区；
+- Relay WebSocket 模式；
+- 当前用户登录后通过 Windows Task Scheduler 自动启动。
+
+不需要安装 WSL、tmux、Git Bash、ConPTY 或 Visual Studio C++ Build Tools。原生 Windows 暂不提供网页 Terminal，也不承诺 Claude Code、OpenCode、UNC 工作区、Windows ARM64 或未登录用户的系统服务模式。
+
+## 2. 安装 Node.js 22
+
+打开 [Node.js 22 官方发布目录](https://nodejs.org/download/release/latest-v22.x/)，下载文件名以 `x64.msi` 结尾的 Windows 安装包并完成安装。
+
+不要仅根据“Latest LTS”按钮安装其他 Node.js 大版本。Remote Codex 当前 Windows 验证基线是 Node.js 22。
+
+安装完成后关闭并重新打开 PowerShell，然后执行：
+
+```powershell
+node --version
+npm --version
+```
+
+`node --version` 应输出 `v22.x.x`。
+
+Git 不是启动 Relay Supervisor 的硬性依赖，但管理代码仓库通常需要 Git。可选安装命令：
+
+```powershell
+winget install --id Git.Git -e --source winget
+```
+
+## 3. 安装并登录 Codex
+
+打开当前 Windows 用户的普通 PowerShell，不需要以管理员身份运行。先只对当前 PowerShell 进程放行脚本：
+
+```powershell
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
+```
+
+该设置会在 PowerShell 窗口关闭后失效，不会永久修改当前用户或整台电脑的执行策略。
+
+运行 Codex 官方 Windows 安装器：
+
+```powershell
+irm https://chatgpt.com/codex/install.ps1 | iex
+```
+
+检查安装结果：
+
+```powershell
+codex --version
+```
+
+检查登录状态：
+
+```powershell
+codex login status
+```
+
+如果尚未登录，运行：
+
+```powershell
+codex login
+```
+
+命令会打开浏览器，由用户完成 ChatGPT 或其他可用方式的登录。无法使用本机浏览器回调时，可以改用设备码：
+
+```powershell
+codex login --device-auth
+```
+
+Codex 会缓存登录状态，Relay Supervisor 后续启动 Codex app-server 时会复用同一 Windows 用户的凭据。不要复制或共享 `%USERPROFILE%\.codex\auth.json`。
+
+## 4. 安装 Remote Codex
+
+在已执行进程级 Execution Policy Bypass 的 PowerShell 中运行：
+
+```powershell
+npm install -g remote-codex@latest
+remote-codex --version
+```
+
+检查所有命令入口：
+
+```powershell
+Get-Command node,npm,codex,remote-codex | Format-List Name,Source,Version
+```
+
+如果 PowerShell 优先匹配到 npm 生成的 `.ps1` shim，并报告脚本被禁用，可以重新执行进程级 Bypass，或者临时显式调用 `npm.cmd`、`codex.cmd`、`remote-codex.cmd`。
+
+## 5. 在 Relay Portal 创建设备
+
+1. 打开 Relay Portal，例如 `https://remote-codex.lnz-study.com/relay-portal`。
+2. 登录 Relay 账号。
+3. 进入 **Devices**。
+4. 点击 **Add**，填写这台 Windows 电脑的设备名称。
+5. 创建设备并保存页面只显示一次的 `rcd_...` device token。
+6. 点击设备行上的 **Copy setup**。
+7. 在二级菜单中选择 **Windows (PowerShell)**。
+
+早期创建且没有保存 token 的设备不能重新显示完整 token。此时需要创建一个新设备。
+
+## 6. 启动 Windows Relay Supervisor
+
+Portal 复制出来的 Windows 命令形如：
+
+```powershell
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
+$env:REMOTE_CODEX_RELAY_SERVER_URL='wss://remote-codex.lnz-study.com'
+$env:REMOTE_CODEX_RELAY_AGENT_TOKEN='rcd_替换为当前设备Token'
+$env:REMOTE_CODEX_RELAY_SUPERVISOR_PORT='45680'
+remote-codex relay-supervisor
+```
+
+Windows 默认端口是 `45680`，macOS/Linux 默认端口是 `45679`。两者不同，允许同一台电脑上的原生 Windows 和 WSL 同时运行 Supervisor。
+
+在 Windows 上，不带子命令的 `remote-codex relay-supervisor` 等价于后台 `start`。命令会：
+
+- 生成本地 Supervisor 的认证信息和 session secret；
+- 将有效配置保存到 `%USERPROFILE%\.remote-codex\relay-supervisor.json`；
+- 收紧配置目录和文件的 Windows ACL；
+- 启动 detached Supervisor 进程；
+- 通过出站 WebSocket 连接 Relay。
+
+关闭 PowerShell 不会停止已经启动的 Supervisor。
+
+### 使用其他工作区根目录
+
+默认工作区根目录是 `%USERPROFILE%`。如果项目统一位于 `D:\dev`，在首次启动命令中额外加入：
+
+```powershell
+$env:WORKSPACE_ROOT='D:\dev'
+```
+
+该值会与 Relay 配置一起持久化。不要把根目录设置为整个系统盘，应该使用专门的代码目录。
+
+## 7. 验证设备在线
+
+检查后台进程：
+
+```powershell
+remote-codex relay-supervisor status
+```
+
+查看最近日志：
+
+```powershell
+Get-Content "$env:USERPROFILE\.remote-codex\logs\relay-supervisor.log" -Tail 100
+```
+
+回到 Relay Portal 刷新设备列表。设备应显示为 **Online**，然后可以点击 **Connect**，添加工作区并创建 Codex thread。
+
+Relay Supervisor 默认只监听 `127.0.0.1:45680`，并主动建立出站连接，不需要在 Windows 防火墙中开放公网入站端口。
+
+## 8. 配置登录后自动启动
+
+后台 `start` 只能保证关闭终端后继续运行，Windows 重启后仍需重新启动。建议为当前用户安装登录计划任务：
+
+```powershell
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
+
+$packageRoot = Join-Path (npm root -g) 'remote-codex'
+
+& (Join-Path $packageRoot 'scripts\windows\install-relay-supervisor-task.ps1') `
+  -PackageRoot $packageRoot
+```
+
+计划任务使用当前用户的 interactive token，以 Limited 权限运行，不使用 `LocalSystem`，也不会把 device token 写入计划任务参数。Windows 重启后必须由该用户登录，任务才会启动。
+
+## 9. 日常维护
+
+```powershell
+# 查看状态
+remote-codex relay-supervisor status
+
+# 停止
+remote-codex relay-supervisor stop
+
+# 重新启动
+remote-codex relay-supervisor start
+
+# 删除保存的 Relay 配置，数据库和 Codex 登录不受影响
+remote-codex relay-supervisor reset
+
+# 更新 Remote Codex
+npm install -g remote-codex@latest
+remote-codex relay-supervisor stop
+remote-codex relay-supervisor start
+```
+
+删除登录计划任务，但保留配置和数据库：
+
+```powershell
+$packageRoot = Join-Path (npm root -g) 'remote-codex'
+
+& (Join-Path $packageRoot 'scripts\windows\uninstall-relay-supervisor-task.ps1') `
+  -PackageRoot $packageRoot
+```
+
+只有明确需要永久删除 `%USERPROFILE%\.remote-codex` 下的数据时，才向卸载脚本传入 `-PurgeData`。
+
+## 10. 常见问题
+
+### `remote-codex.ps1 cannot be loaded`
+
+当前 PowerShell 没有允许 npm PowerShell shim。运行：
+
+```powershell
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
+```
+
+也可以绕过 PowerShell shim：
+
+```powershell
+remote-codex.cmd relay-supervisor status
+```
+
+### 找不到新安装的命令
+
+关闭并重新打开 PowerShell，然后检查：
+
+```powershell
+Get-Command node,npm,codex,remote-codex | Format-List Name,Source
+```
+
+### 设备持续 Offline
+
+依次检查：
+
+```powershell
+codex login status
+remote-codex relay-supervisor status
+Get-Content "$env:USERPROFILE\.remote-codex\logs\relay-supervisor.log" -Tail 100
+```
+
+常见原因包括 device token 错误或已撤销、Relay URL 错误、公司网络阻止出站 WSS、端口被占用，或者当前用户没有 Codex 登录状态。
+
+## 11. 敏感数据位置
+
+以下文件可能包含 token、session secret 或登录凭据：
+
+- `%USERPROFILE%\.remote-codex\relay-supervisor.json`
+- `%USERPROFILE%\.remote-codex\relay-supervisor-state.json`
+- `%USERPROFILE%\.codex\auth.json`
+
+不要把这些文件提交到代码仓库、上传到 issue 或原样附在诊断报告中。分享日志前应删除 token、密码、session secret、Authorization header 和 `controlToken`。
+
+## 参考资料
+
+- [Remote Codex 原生 Windows 支持](windows.md)
+- [OpenAI Codex CLI](https://learn.chatgpt.com/docs/codex/cli)
+- [OpenAI Codex authentication](https://learn.chatgpt.com/docs/auth)
+- [Node.js 22 Windows 发布文件](https://nodejs.org/download/release/latest-v22.x/)
+- [PowerShell execution policies](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies)