# Gateway 升级说明

适用范围：`@rcodex-lab/gateway`

## 升级前确认

- 现有数据目录已经保留
- 账号、密码、token 和可访问目录配置已确认
- Node.js 版本为 22 或更高
- 当前用户已有可用的 ChatGPT 登录、API Key 或 Provider 凭据

## 标准升级步骤

普通用户默认使用 npm 部署：

```bash
npm install -g @rcodex-lab/gateway
rcodex-gateway setup
rcodex-gateway service install
rcodex-gateway service start
rcodex-gateway service status
```

如果已经安装过 Gateway，升级时执行：

```bash
rcodex-gateway service update
```

该命令在当前 Gateway 所在的 npm 目录更新包，成功后使用新版 CLI 刷新服务定义、重启并显示最终状态。npm 更新失败时不会停止现有服务，也不会自动使用 sudo。

常用服务命令：

```bash
rcodex-gateway service install
rcodex-gateway service start
rcodex-gateway service status
rcodex-gateway service restart
rcodex-gateway service update
rcodex-gateway service stop
rcodex-gateway service uninstall
```

首次安装时需要执行 `service install`。升级后建议再次执行，以便覆盖为当前版本的任务或服务定义；该操作不会覆盖 `gateway.env` 和数据目录。Windows 使用当前用户计划任务，macOS 使用 LaunchAgent，Linux 使用 user-level systemd。这样 Gateway 能继续读取当前用户的 Codex CLI 登录态。

Windows 新安装默认使用 `%LOCALAPPDATA%\rCodex\Gateway\gateway.env`；已有 `C:\ProgramData\rCodex\Gateway\gateway.env` 会继续复用。Windows 计划任务在当前用户登录后无窗口运行，不要求管理员权限或 Windows 账户密码，关闭执行安装命令的终端不会停止 Gateway。升级后必须重新执行 `service install`，以覆盖旧任务定义并移除旧 PowerShell 启动文件；该操作不会覆盖配置和数据。`service start` 会验证后台 PID 和 `/healthz`，`service status` 会显示运行模式、任务、进程、HTTP 健康状态及日志路径。

Gateway npm 包会同时安装官方 `@openai/codex` 运行时，不再要求单独全局安装 Codex CLI。旧 `gateway.env` 中的默认值 `CODEX_COMMAND=codex`，以及指向 VS Code `openai.chatgpt-*` 扩展版本目录的历史 Codex 路径，都会自动使用内置版本；其他显式自定义命令继续保留。内置运行时不会自动完成账号或 Provider 认证。

需要临时调试时，也可以继续使用 `rcodex-gateway start` 在当前终端前台运行；关闭终端后前台进程会停止。如果没有安装后台服务，升级后停止旧的前台进程，再重新执行 `rcodex-gateway start`。

## 这次版本需要注意什么

`1.4.22` 是一次 App 端发布版本：本次版本优化了会话状态信息、计划查看和长会话耗时展示。 Gateway 可继续保持 `1.4.21`。