The project's README from github.com/piperhex/remoteai. As one markdown file: README.md.
[!IMPORTANT] Codex Switch 现已更名为 Remote AI。 仓库也已由
codex-switch迁至 piperhex/remoteai,欢迎更新收藏,继续关注后续版本。
For English documentation, please see README_EN.md.
Remote AI 是一款面向 Codex 的图形化 AI 编程工作台,以直观易用的界面整合对话编程、项目管理与多账号管理。 你可以直接在应用中与 Codex 对话,理解代码、实现功能、排查问题,并随时查看执行进度和文件改动。 它还提供账号登录与切换、用量查看、第三方 Provider、本地热切换代理、Token 分析、Skills 市场和一键换肤, 支持在本机启动网页版,也可连接自建后端与移动端,实现跨设备协同管理。
QQ 技术交流群:972062132
访问 RemoteAI Web,在浏览器中连接电脑使用 Codex。
使用前,请先安装 Remote AI PC 端, 进入 首页,按页面提示完成 Codex 安装。 保持 PC 端运行并联网,在网页端登录与 PC 端相同的云端账号,即可连接电脑开始使用。
Codex GUI 是内置的图形化对话工作区。选择项目后,用自然语言描述任务即可开始,也可以不选项目直接提问。 从提出需求到查看结果,项目、对话和改动都集中在同一个界面中。

/ 选择命令或技能。首次使用可按页面提示下载 Codex。更多操作请参阅 Codex GUI 使用说明。




内置 300+ 套主题预设,并兼容 Fei-Away/Codex-Dream-Skin。


点击菜单中的 2FA,即可在主窗口右侧查看和管理验证码。

auth.json,包括常见第三方 JSON 导出及多账号 JSON 文件。$CODEX_HOME/auth.json(默认是 ~/.codex/auth.json)。.cs 备份包导出和恢复本地账号与服务商配置。127.0.0.1:15722 的本地代理使用,并支持在官方账号与 Provider 间热切换。--headless --port 无界面运行。从 Releases 下载 Linux x64 .deb 包,
将下面的文件名替换为实际下载的文件名:
sudo apt update
sudo apt install "./codex-switch.deb"
csw
纯命令行 Ubuntu 服务器需通过虚拟显示启动:
sudo apt install xvfb xauth dbus-x11 xdg-utils
xvfb-run -a dbus-run-session -- csw --headless --port=18080
默认访问地址为 http://127.0.0.1:18080。安装包使用者无需安装 Node.js 或 Rust。
后台服务、开机自启、远程网页访问、代理 Key 和常见问题请参阅 Linux 安装与使用。
以下要求用于从源码开发和构建。
Ubuntu 请先安装 Tauri 的 Linux 构建依赖:
sudo apt update
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libappindicator3-dev librsvg2-dev patchelf xdg-utils
安装依赖并启动桌面应用:
npm install
npm run dev:app
使用演示数据启动浏览器预览(不会访问真实凭据):
npm run dev
启动管理控制台或云端后端:
npm run dev:admin
npm run dev:backend
启动 Expo 移动端:
npm run start -w @codex-switch/native
移动端需要已部署的云端后端,会读取已同步的账号摘要和短期 Codex access token,由手机直接刷新用量与重置卡,同时显示在线 PC,并可分别切换每台 PC 的官方模型或已同步 Provider。远程切换 Provider 前,需要先在目标 PC 启动本地代理;在官方模型与 Provider 间切换后,移动端会提示重启 ChatGPT/Codex。详细配置请参阅 移动端文档 和 管理后端文档。
构建桌面安装包:
npm run build:app
在 macOS 上构建同时支持 Apple Silicon 和 Intel 的通用包:
npm run build:app:mac
在 Windows 上构建 ARM64 安装包:
rustup target add aarch64-pc-windows-msvc
npm run build:app:win-arm64
Windows ARM64 构建还需要在开发环境中安装带 ARM64 构建工具的 MSVC C++ 工具链。Ubuntu 上运行 npm run build:app 会生成 .deb 和 AppImage 安装包。
运行全部前后端检查:
npm run check
auth.json 或导入兼容 JSON 导出。兼容导入支持单个对象、数组、{ "accounts": [...] } 包装对象和逐行 JSON,并识别常见的令牌与会话字段名。auth.json。使用账号工具栏的“导入”和“导出”可恢复或创建包含所有本地账号与服务商配置的 .cs 备份。导入会按稳定标识合并记录,并不会将备份当成可随意公开的无密钥导出文件。
“第三方服务商”页面用于管理兼容 OpenAI Responses 或 Chat Completions 的接口、API 密钥、模型列表,以及由 Codex 还是 Remote AI 控制模型选择。三方 Provider 仅可在本地代理运行时使用;代理会监听 127.0.0.1:15722 并使 Codex 指向该地址,从而支持热切换。
启动 PC 本地代理后,在代理设置中添加 API Key,再开启“监听局域网”。可为不同设备或使用者分别添加 Key,设置名称、启用状态和总额度(USD);额度留空表示不限,填 0 表示暂时没有可用额度。已有的局域网 Key 会保留。
首次使用时,点击“添加 Key”,填写名称并保存,密钥留空可自动生成。 列表为空或没有已启用的 Key 时,“监听局域网”开关会变灰。 保存后可在对应条目旁复制代理 API Key;该 Key 与网页登录的访问密钥不同。
每个 Key 旁会显示累计 Token、预估成本和剩余额度。成本按请求结束时的模型价格设置累计,调价只影响后续请求;清理会话或 Token 历史不会重置这些累计数据。额度用完后不再接受新的生成请求,已经开始的请求会继续完成,因此累计成本可能超过设定额度。
若部分请求未返回完整用量,Key 会标记为“用量待确认”,设有额度的 Key 会暂停新请求。管理员核对成本并调整额度后,可在编辑时勾选确认以恢复使用;已确认的累计用量会保留。
在下游 Remote AI 添加上游设备的局域网地址和对应 Key,保存后可自动识别并显示该 Key 的剩余额度。也可在余额查询设置中选择“Remote AI”。额度用完后仍可刷新余额;不同 Key 只能查询各自的额度。
Remote AI 支持通过桌面深链从 sub2api、newapi 以及其他兼容页面一键导入中转站 Provider。网页按钮只需要打开下面的自定义协议链接,浏览器会唤起已安装的 Remote AI,并把参数交给桌面端保存:
cswitch://v1/import?resource=provider&app=codex&name=站点名称&homepage=https%3A%2F%2Fexample.com&endpoint=https%3A%2F%2Fexample.com%2Fv1&apiKey=你的API密钥&balancePlatform=sub2api
Remote AI 只注册自己的 cswitch:// 协议。所有参数值都必须经过 URL 编码,尤其是 name、homepage、endpoint 和 apiKey;API 密钥不要直接拼接未编码的特殊字符。
参数说明:
resource=provider:固定值,表示导入 Provider。app=codex:按支持 OpenAI Responses 的第三方中转站 Provider 导入,不会识别为官方 OpenAI Provider。app=claude、app=gemini 或 app=grokbuild:按兼容 Chat Completions 的自定义 Provider 导入,适合只提供 Chat Completions 的中转站。name:在 Remote AI 中显示的 Provider 名称。homepage:站点主页,保留给兼容页面使用。endpoint:实际 API Base URL,例如 https://example.com/v1。apiKey:中转站 API 密钥。balancePlatform=sub2api 或 balancePlatform=newapi:可选,用于标记对应的余额查询平台;也接受兼容页面常用的 platform 参数名。页面只需提供余额平台;未提供余额查询地址和 Token 时,Remote AI 会根据 endpoint 补全平台默认地址,并复用导入的 API 密钥。导入时还会自动从中转站加载可用模型;加载失败时使用链接指定的模型或程序默认模型,不会中断导入。
因此,sub2api 使用的核心格式不是账号 JSON,而是上面的 Provider 深链格式:把 balancePlatform 设置为 sub2api,把 endpoint 和 apiKey 换成该站点实际值即可。newapi 只需将其改为 newapi。深链会在桌面端后台解析并保存,不会把密钥写入前端日志。
官方账号模式下,“自动切号”会在收到额度响应后刷新已保存账号,并选择主用量窗口使用率最低的符合条件账号。429 响应会在本地代理内按递增间隔重试,设置页可调整最长重试时间。“Token 汇总”窗口展示该代理观察到的请求用量。
设置页按用途分组,可配置界面语言、主题色、关闭到托盘、隐私模式、悬浮用量球、
全部账号的全局自动刷新、当前账号的独立刷新、多个 Codex Home 路径、
本地数据目录快捷入口,以及代理诊断导出。自部署用户可在 settings.json 中将 showCustomCloudServer
设为 true,以显示云端服务器地址设置。
已安装的桌面客户端可以在桌面界面运行时附加启动网页版,也可以无界面启动网页版服务。
默认仅监听 127.0.0.1;如需从同一局域网内的可信设备访问,可在设置中开启“监听局域网”。
无界面模式不会创建主窗口、托盘或悬浮球,命令行端口只对本次运行生效:
csw.exe --headless --port=18080
# 也支持:csw.exe --headless --port 18080
启动后通过 http://127.0.0.1:18080 访问。--headless 必须与 --port 同时使用,端口范围为 1-65535。
Linux 使用 csw 命令;无桌面服务器的启动方法见 Linux 安装与使用。
启用网页局域网监听后,持有网页版访问密钥的用户拥有完整管理权限;需要调用模型的设备应使用单独的代理 API Key。
系统托盘菜单可以显示控制台、切换账号、重启 ChatGPT 或退出。悬浮用量球展示当前账号的主用量窗口:左键会刷新该账号,悬停可展开,支持拖动位置,并在右键菜单中提供相同的快捷操作。
可在设置页添加、编辑、启用或停用多个 Codex Home。所有已启用目录会同时接收账号与 Provider 配置;
删除全部记录后会优先读取
CODEX_HOME 环境变量,否则使用 ~/.codex。云端后台还可分别配置 Windows 与 macOS 的推荐路径,
客户端只展示当前系统对应的路径。该设置不会修改系统环境变量。受管账号副本、
服务商配置、应用设置、云令牌、代理日志和 Token 用量历史均保存在操作系统的应用数据目录中。
在设置页填写 Base URL 前,云端登录保持关闭。登录后,手动同步和正常的账号/服务商变更会与该服务器交换完整凭据载荷;移动端调用 /sync/accounts/summary 获取短期 Codex access token,但不会收到 refresh token、ID token 或完整 auth.json。
apps/desktop/ Tauri 桌面应用工作区
src/ React 前端
api/ Tauri 命令和浏览器预览适配层
components/ 可复用展示组件
hooks/ 账号、通知和自动刷新状态
pages/ 页面级组合
utils/ 无副作用的格式化工具
src-tauri/src/ Rust 后端
apps/admin-ui/ React 管理控制台工作区
apps/admin-go/ Go 云端后端与生产部署
apps/admin/ 已冻结的 NestJS 兼容测试基线
apps/native/ Expo 移动端账号用量伴侣应用
docs/ 架构和开发文档
更多文档:
推送版本标签后,GitHub Actions 会自动发布构建产物:
npm run release
npm run release-beta
npm run release 会读取 package.json,将补丁版本加 1,同步更新桌面端和移动端的版本文件(包括 Android versionCode)、创建提交和带注释标签,然后推送分支与标签。npm run release-beta 会创建或递增类似 v0.1.1-beta.0 的预发布标签。可通过 npm run release -- v0.2.0 或 npm run release-beta -- v0.2.0-beta.1 指定准确版本。
发布工作流构建 Windows x64、Windows ARM64、Ubuntu/Linux x64、macOS Apple Silicon 与 Intel、Android APK 以及未签名的 iOS Release .app.zip,并上传到对应 GitHub Release。iOS 产物用于验证构建,安装到设备或提交 App Store 前仍需要 Apple 签名凭据。
欢迎提交 Issue 和 Pull Request。开始前请阅读 贡献指南,尤其是关于凭据脱敏、职责边界和本地验证的要求。
Remote AI 使用 Apache License 2.0,与官方 OpenAI Codex 仓库一致。
Remote AI 是独立开发的第三方软件,与 OpenAI 及其 Codex 产品不存在隶属、关联、授权、认可或官方合作关系。