Codex Mobile Bridge · 多客户端远程工作台

v2.1.4 正式版：发布页 · 完整更新说明 · 手机安装说明。改善公网启动、长会话加载与 Web 复制，新增可选的网络变化自动恢复。

简体中文 · English

双语介绍与使用演示 ↗ · 下载桌面与手机 App

v2.1.3 更新

• 多目标通知：可以添加多个独立 Webhook，分别启停、测试和编辑。提供通用自定义、飞书、钉钉、Discord、Telegram 可编辑 JSON 模板；飞书与钉钉支持可选签名。已保存地址与密钥默认隐藏，测试仅使用已保存配置。配置说明
• 图表阅读：聊天与 Markdown 文件中的 Mermaid 代码块可预览、查看或复制源码，并全屏缩放。iOS 同步修复图表子页面导航；需要更新配套 App。
• 弱网与接入：静态资源按内容缓存，减少重复打开时的传输；Windows 包只保留支持的 Electron 语言资源。修复 DeepSeek Harness 折行配置识别，并为 iOS 网关不可达提供原生重试与返回入口。
• 手机交互：弹窗不再被原生“更多”入口遮挡，优化焦点外观和补充回答输入框的键盘可见性。

v2.1.2 更新

• 终端直接输入：手机与宽屏 Web 默认直接输入，改善中文输入、光标与焦点恢复，新增 Enter；保留可选的“编写后发送模式”和分阶段 Tab 路径补全。
• 交互与连接：改善 OpenCode 类终端 CLI 的触摸滚动、鼠标选择与退出后的布局；减少网络往返造成的额外等待，临时断线后自动恢复仍有效的终端。
• 显示与兼容性：终端字号独立调节为 6–24px，修复小字号、中文混排与背景边界；Windows 完整携带 ConPTY 组件，修复鼠标事件丢失和安装器漏装组件。
• 阅读设置：主题与语言移到设置顶部，正文字号扩为 10–32px，代码字号扩为 8–28px。

v2.1.1 更新

• 账号与模型：三个客户端统一账号卡片与模型选择；模型目录缓存优先，按电脑、账号与接入隔离，显示更新时间，支持手动及 12 小时更新。
• 草稿与文件：跨聊天和电脑保留未发送草稿；定位文件平滑滚动并高亮，左上角直接返回聊天列表；支持工具截图预览。
• 日常体验：修复快速滑动回跳、列表与模型重复加载，优化 iOS 通知跳转；网关和手机可跳过当前更新，修改密码可选择保留有效手机绑定。

v2.1.0 更新

• CLI 与文件阅读：从手机或 Web 阅读、显式恢复 Codex / Claude Code CLI 会话；源码、PDF 和自包含 HTML 有专门的阅读预览。
• 连接与列表：接入已有 HTTPS 穿透或反向代理；Codex 列表逐主机呈现，Claude 混合列表按日期排序，来源标签持续可见。
• 跨平台体验：改善 Windows 连续终端与 Claude 初始化、DSH 主机识别、iOS Safari 输入时的视区和滑动布局；所有客户端停用后仍可管理网关。

v2.0.3 更新

• Android 更新：在 App 内下载并安装新版，自主选择手机下载或电脑下载；下载完成后可继续安装或导出 APK。详见手机安装与升级。
• 第三方通知：手机与 Web 可选择 Bark（iPhone）、ntfy（Android）或 PushPlus（微信），配置、保存并测试，与电脑网关共用设置。
• 搜索与布局：搜索框保留「搜索 / Search」，筛选按内容分配宽度；改善英文、横屏和平板列表，支持 Claude/DSH 下拉刷新，恢复后清除旧错误提示。
• 连接与工作台：手机安全保留有效绑定并尝试恢复登录，改善 Claude 重连与初始化；设置入口和文件传输保存文案更清晰，关闭工具标签时保留仍有内容的分屏。

文件阅读与预览

• 定位与返回：聊天文件链接可平滑定位并高亮目标 3 秒。左上角返回直接回聊天列表；文件区上级目录按钮与系统返回仍支持层级导航，全屏的系统返回先退出全屏。
• 源码阅读：常见代码显示语法高亮和行号；点击“自动换行”让长行适合屏幕，或切回“原始行宽”。复制代码保留原文，不带行号；这是只读预览，不修改文件。未知语言与较大文本使用纯文本。
• PDF 阅读：手机滑动翻阅、双指缩放，电脑浏览器保留翻页和缩放按钮。有文本层时可选择文字，扫描件不提供 OCR；不同尺寸的页面分别适配宽度。快速缩放时先保留原画面，再替换完成的新画面，减少闪烁。
• HTML 阅读：在“预览 / 源代码”之间切换。自包含 HTML 的内联交互和动画可运行；外部资源、CDN、后端请求、弹窗和表单提交不受支持。预览与网关登录信息、父页面和手机原生接口隔离。
• Mermaid 图表：Markdown 文件与聊天使用相同的图表、源码和全屏阅读入口，见图表阅读说明。
• 紧凑操作与全屏：下载、复制或预览操作位于文件描述右侧；下载旁可展开全屏。全屏进出保留 PDF 位置和 HTML 状态；切换文件标签后返回 PDF 仍保留位置，HTML 则重新加载。

CLI 会话（v2.1.0 正式版）

现有 CLI 会话可在手机和 Web 中发现、阅读；点击“继续会话”后可接入或恢复原 CLI 会话，原终端无需保持打开。若 Codex App 已接续该聊天，网关会复用经核验的现有执行连接；未发现该连接时，仅会在显式操作时接入或启动已安装的原生托管 daemon。连接后支持模型与推理强度、Skill、普通/计划模式、权限切换，以及兼容本机/SSH 原生 CLI 运行时的 Goal 操作。设置中的“SSH 连接诊断”可查看本机与远端状态、复制摘要或导出脱敏文件；旧版手机 App 需更新后才能导出。详见 CLI 接入说明。

Codex 与 Claude CLI 接入分别在各自账号管理中配置；本机 CLI 同步需主动启用，并分别显示桌面与 CLI 核验结果，SSH 保留各服务器配置。Claude 可从已有本机或 SSH 项目创建 CLI 聊天，保留所选配置与工作目录。来源标签始终显示；多种会话类型可筛选；Claude 已知上下文容量显示蓝色用量圆环，未知容量显示中性环。

平台与接入

桌面安装包覆盖 macOS、Windows 和实验性 Linux x64/ARM64；Codex 与 Claude Code CLI 支持本机及已配置的 SSH 执行端。Linux 的 Claude Code CLI 与 Claude Desktop 是独立通路，Desktop 自动连接适用于 macOS / Windows。详见 CLI 接入说明和 Linux 文档。

v2 工作台

• 多应用接入：自动扫描已安装客户端，配置就绪后启用；桌面、Web 和手机可管理启停及重连。Claude Code / Cowork 分组可折叠，应用切换支持图标与可关闭的左右滑动。
• 聊天之外的工具：文件、Git、连续终端、Codex 临时侧边聊天与子智能体历史以标签呈现；宽屏、平板和折叠屏支持可调整的分屏，窄屏保留单栏。
• 文件与图片：聊天链接可定位所在文件夹或下载；可实时调整普通下载阈值，文件列表支持显式下载大文件/目录。下载浮窗提供进度、速度、暂停和继续；图片支持双指、滚轮、拖动和双击缩放。
• 账号与上下文：按客户端查看当前接入、可用模型及上游提供的额度；Codex 和 Claude 上下文用量显示在权限旁。Codex 保留 Fast、Skills、计划/目标、官方额度和重置卡能力。
• 多台电脑与通知：Android/iOS 扫码保存电脑，按最近访问排序，手动刷新在线状态。应用图标显示网关维护的未读数，点击直达对应聊天列表；普通手机包的后台通知仍需借助 Bark、ntfy 或 PushPlus。
• 多种网络入口：局域网、Cloudflare 临时/固定 HTTPS、Tailscale 固定 HTTPS、自有服务器 + SSH，以及 NAS/已有反代。

社区项目，与 OpenAI、Anthropic 或 DeepSeek 无隶属关系。依赖客户端内部接口，上游更新可能需要适配。电脑休眠或离线时无法远程操作；不能承诺 Claude 冷启动免解锁。平台与历史实测范围见 验证记录 和 桌面接入说明。

支持 macOS、Windows，以及实验性 Ubuntu x64/ARM64。Linux 安装、VMware 网络及能力边界见 Linux 文档。开发与定向修改请先阅读 代码架构导航 和 验证指南。

Codex 消息编辑、分支与复制

• 用户消息下方可复制内容。最近一条选择「编辑并重新发送」；更早的消息选择「编辑并新建分支」，原会话保留。
• 已完成的回答下选择「从这里分支」，新会话保留截至该轮的历史，等待你继续输入。聊天详情中可返回来源会话。
• 回复支持完整 Markdown 复制，代码块和 Mermaid 源码可单独复制；长回复自动读取完整正文。Web 点击复制会直接写入剪贴板，局域网 HTTP 也会尝试兼容复制；仅在浏览器拒绝自动复制时显示可选文本及重试按钮。
• 原地编辑要求任务已停止，会重新生成回答。编辑和分支不会撤销既有文件修改；新旧会话共享工作目录。
• 分支需要 Codex 运行时同时支持指定轮次与目标续跑延迟；旧版会提示更新 Codex App。复制与最近消息编辑不受此分支能力限制。创建分支不会主动发送模型请求。
• 结果不确定时先检查聊天列表，重复提交同一请求不会再次执行。分支已创建但连接失败时，修改保留为该分支的编辑草稿。

下载与快速开始（推荐）

日常使用直接下载桌面 App，无需 Agent 帮忙部署，也无需安装 Python、Node.js 或打开终端。下列链接对应 v2.1.3 正式版。

| 系统 | 下载 | 打开方式 | | --- | --- | --- | | Windows x64（推荐安装包） | 下载 Setup.exe | 运行安装包，从快捷方式打开 | | Windows x64（免安装） | 下载完整 ZIP | 完整解压后运行 Codex Mobile Bridge.exe，不要单独移动 exe | | macOS Apple Silicon（M 系列） | 下载 arm64 DMG | 打开 DMG，将 App 拖入“应用程序” | | macOS Intel（英特尔） | 下载 x64 DMG | 打开 DMG，将 App 拖入“应用程序” | | Ubuntu x64（实验性） | 下载 .deb | Ubuntu 22.04；安装后以普通用户启动 | | Ubuntu ARM64（实验性） | 下载 .deb | Ubuntu 22.04 ARM64；不含 32 位 ARM |

查看所有版本与更新说明 · 下载 SHA256 校验文件。两种 Mac 同时提供 ZIP，供应用内更新或手动替换使用。Windows ARM 暂无专用安装包。Mac 版采用本地完整性签名但未公证，首次打开可能需要手动允许；Windows 版未做证书签名。详见下方 macOS 首次打开说明。

1. 安装并登录要使用的桌面客户端，打开 Codex Mobile Bridge。在 客户端与接入 检查扫描结果，完成需要的授权，并启用配置就绪的客户端。
2. 在 网络访问 保留局域网访问或添加 HTTPS 入口，保存后从概览或客户端页点击 启动网关。已有配置时沿用原端口。
3. 手机连接可达的网络，使用手机 App 的 扫码连接电脑 扫描概览中所选地址的配对码。浏览器也可扫描登录码或手动打开地址登录。
4. 选择应用和会话，继续聊天或打开工作台。使用期间保持电脑、网关与相应客户端运行。

Android APK、iOS 未签名 IPA 与 Xcode 源码包见同一 v2.1.3 Release。Android 覆盖安装以保留数据；iOS 需自行签名，暂无 App Store/TestFlight 分发。源码运行与自定义部署见后面的部署 Agent 执行说明。

App 内更新

beta.5 / beta.6 的更新检查存在 HTTP 415 问题，需要手动安装一次 beta.7 或后续版本。 先停止网关、退出 App，再替换程序，保留原数据目录；修正版之后可继续使用应用内更新。

从 v0.2.0-beta.5 起，可在桌面 App 的「应用更新」中检查新版、查看说明并点击「更新并重启」。下载与校验完成后短暂重启网关，保留登录、网络、通知和关注聊天配置；失败时尝试恢复原版本。此前版本需要先手动安装一次支持更新的版本。使用临时 HTTPS 时，重启后请打开最新地址。发布与恢复说明见 桌面更新文档。

Windows beta.7 / 1.0.0 用户：旧更新器可能因目录占用报 WinError 32 并回退。请先在托盘选择“停止网关并退出”，再用 2.1.3 Setup.exe 安装到原位置；无需卸载或删除数据。1.1.0 修复后续更新的目录占用问题。

Android v2.0.3 起支持应用内 APK 更新，并可选择手机下载或电脑下载；旧版首次升级可手动覆盖安装。电脑协助方式需要配套网关，下载失败可重选方式，已完成的包可继续安装或保存。iOS 仍按签名安装指引升级，详见手机说明。

手机阅读与显示设置

• 手机「外观与显示」与 Web 设置并列放置底部 App 图标开关、应用管理、第三方通知；英文使用简短标签。文件传输的保存按钮仅保存传输大小配置。
• 对话页收拢顶部导航，点击标题可查看完整名称、项目、运行设备和模型信息。
• 点击模型、提醒、Skill 右侧的箭头，可收起或展开下方输入框与发送/停止栏。收起保留草稿，发送成功不会自动收起；失败时展开错误提示。
• 在右上角 “··· → 显示设置” 独立开关 思考摘要、执行过程。执行过程包含命令、工具调用、文件变更与中途进度说明；关闭两项可专注阅读回复。用户消息、错误和待确认卡片仍保留；缺少阶段标记的旧回复也会显示。
• 可选浅色、深色或跟随系统，自定义强调色、正文字号、代码字号和阅读间距。设置即时生效并保存在当前浏览器；电脑网页同样可用。

多账号与 API 切换

Codex 支持在 Bridge 桌面端添加官方账号、自定义 API 或扫描导入本机配置，在桌面端与 Web 切换已保存接入。切换会重启官方 Codex 桌面应用，Bridge 网关保持运行。当前接入置顶；官方账号旁显示额度与重置卡数量，API 聊天按上游提供模型列表。参见使用与恢复说明。

桌面端可扫描当前或指定 Codex 数据目录，选择导入已有官方凭据、API 提供商和 profiles；API 表单支持从上游获取模型列表并选择默认模型，也可手动填写。

官方账号额度与重置卡

电脑控制面板和手机端按当前客户端展示「账号与接入」。官方账号卡片展示额度百分比、恢复倒计时与具体时间、可用重置卡和服务提供的 Credits。API 接入展示接入状态与模型信息。

Codex 打开账号页时自动读取数据，可见页面每五分钟查询一次，也可手动刷新；倒计时在本地更新。后续查询保留上次成功结果，并在旁边显示「查询中」；成功后替换，失败时保留旧值和最后成功时间。

从 v2.1.0 起，Claude 仅在点击「查看剩余额度」时查询，打开、返回及定时刷新面板只显示已保存快照。查询失败保留旧结果及原成功日期时间；尚未成功查询时明确提示。此改动减少非主动的额度凭据读取，不代表所有钥匙串授权提示均已消除；DSH 的既有查询方式不变。

v2.0.0 支持为当前及其他已保存的官方账号手动使用重置卡，无需先切换登录，也不依赖 Codex 的“允许代理使用用量重置”开关。确认前显示账号与卡片到期时间，等待五秒后才可使用；请求中断后重试原请求，不会生成新的消费标识。

v2.0.0 在线查询订阅周期日期，显示剩余时间和具体日期；接口受限或未提供日期时显示「订阅有效期暂未确认」。日期表示查询到的当前周期，不代表取消订阅，不会用登录令牌失效时间或旧登录记录推算订阅到期。账号凭据不传给手机。

「提醒与 Codex Desktop 更新」可分别开启额度不足、确认恢复、重置卡到期、订阅周期以及桌面新版本提醒。默认关闭，通过已配置的 Bark、ntfy 或 PushPlus 发送；电脑与网关需要保持运行。详见账户信息与桌面更新。

登录有效期与设备管理

• 网页登录默认勾选 记住密码（7 天免登录）：保存登录 Cookie，不保存明文密码，持续使用会续期；七天未刷新后需重新登录。取消勾选使用普通有效期的浏览器会话 Cookie。
• 同一 IP 连续输错 5 次即自动封禁，网页显示剩余次数，失败计数与封禁记录在重启后保留。正确登录会重置连续失败次数；封禁后只能在电脑 App 的 登录与设备 → 自动封禁 IP 解除并重置次数。
• 消息通知 → 登录安全通知 默认开启，封禁时通过已启用的 PushPlus、Bark、ntfy 发送通知，可单独关闭；关闭通知不关闭封禁。
• 普通登录有效期在 登录与设备 → 登录有效期（小时） 中设置，保存后重启网关生效。修改账号或登录方式会撤销此前登录；修改密码默认撤销全部登录，也可取消勾选“同时撤销所有已绑定手机”，只保留当前有效且已标记为可信手机的登录，普通浏览器登录须重新登录。此标记沿用现有手机 User-Agent 判定，并非不可伪造的设备身份。保留时须先停止网关。普通网关重启和 App 更新保留未过期登录。
• 0 表示不自动过期。浏览器仍可能清理长期未使用的 Cookie；退出登录、清除浏览器数据或更换访问域名后需要重新验证。
• 登录设备 展示一次浏览器登录的 IP、浏览器标识、登录时间、最近访问（最多约一分钟延迟）和到期时间。撤销登录 只移除该登录，之后可重新验证；封禁此 IP 会撤销该 IP 的全部登录并禁止重新登录。
• IP 白名单默认关闭，启用后仅允许列表内地址；黑名单优先。支持精确 IPv4 / IPv6 地址，每行一个。规则保存后立即生效，可随时从电脑 App 解除，不需要手机端权限。
• 网页无法读取手机网卡 MAC，iPhone 还可能使用轮换的私有 MAC。记录代表浏览器登录，并非不可变的硬件身份。手机切换网络可能更换 IP；多个设备共用公网 IP 时会一起受 IP 规则影响。
• 局域网直连使用连接来源 IP。本机 HTTPS 隧道受信任；NAS 等外部反向代理须在 代理 IP 设置 填写可信代理地址，并正确追加或覆盖 X-Forwarded-For。网关只从可信来源读取转发头。未转发客户端地址时会标注代理 IP，封禁代理 IP 会影响其所有客户端。

macOS 首次打开：提示“已损坏”或开发者无法验证

当前 Mac 版具有本地完整性签名（ad-hoc），没有 Apple Developer ID 签名和公证，首次打开仍可能被 macOS 拦截。旧版 v0.2.0-beta.1 还存在包签名缺陷，请优先下载 v1.1.0 或后续版本。

1. 从本仓库的 Release 下载对应芯片的 DMG 或 ZIP，以及 SHA256SUMS.txt。计算下载文件的 SHA-256，与校验文件中同名文件的一行比较；不一致时重新下载，不要放行。以下以 2.1.3 的 M 系列 Mac DMG 为例，其他文件请替换文件名：

shasum -a 256 "$HOME/Downloads/Codex-Mobile-Bridge-2.1.3-macOS-arm64.dmg"

1. 打开 DMG，将 Codex Mobile Bridge.app 拖入“应用程序”，再推出磁盘映像；ZIP 则先解压并移动 App。尝试从“应用程序”打开后，前往 系统设置 → 隐私与安全性 → 仍要打开，按系统提示确认。
2. 如果没有“仍要打开”，或仍提示“已损坏”，在已核对来源与哈希的前提下，打开终端，仅移除这个 App 的下载隔离标记，然后重新打开：

xattr -dr com.apple.quarantine "/Applications/Codex Mobile Bridge.app"

如果 App 放在其他目录，请把引号内路径换成实际位置。这不会授予 Apple 信任或公证，也不需要关闭 Gatekeeper、SIP 或全局安全检查。

本地完整性签名可以检查包是否完整，不能证明发布者身份，也不等于 Apple 已检查应用。手动放行仅适用于你确认信任的下载。参见 Apple：安全地打开 Mac 上的 App。

桌面 App 使用说明

直接使用上方 Release 安装包即可。桌面 App 管理网关与各客户端接入，任务执行和模型认证仍由相应的原桌面客户端管理。

使用桌面 App

下载方式见上方快速开始。开发构建可从 GitHub Actions → Desktop builds 获取，也可按下文在本机构建。

打开后可设置：

• 概览：启停网关、查看所有访问入口、复制地址和生成扫码登录码。
• 客户端与接入：扫描 Codex、Claude、DSH，检查配置与连接状态，管理启停、账号、额度和模型；也可启停网关。
• 网络访问：局域网端口、Cloudflare、Tailscale、服务器 SSH、NAS/反代及额外 HTTPS 地址。
• 登录与设备：登录方式、有效期、可信设备、撤销登录和 IP 访问规则。
• 消息通知：Bark、ntfy、PushPlus、手机收件箱、已关注会话与通知测试。
• 应用与维护：启动与数据目录、传输阈值、网关应用更新、运行日志和高级连接诊断。

Windows 关闭窗口会收起到系统托盘；双击托盘或再次启动 App 可恢复同一窗口。托盘可打开或复制手机地址（优先 HTTPS，其次局域网），也可选择“停止网关并退出”或“退出控制面板（保留网关）”。默认数据保存在当前用户的 App 数据目录，卸载不自动删除配置与凭据。手动更新、移动解压版或卸载前，请先停止网关并退出控制面板，避免后台运行时仍占用程序文件。“打开 App 自动启动”不等于 Windows 开机启动。

右上角可切换 简体中文 / English，与 Mac 新界面位置一致。首次启动按系统语言选择（英文系统使用英文，其他语言回退简体中文），之后记住手动选择，并保留旧 Windows 版已保存的语言偏好。切换立即更新桌面页面、连接配置、状态提示和 Windows 托盘，不重启网关、不丢弃未保存配置。桌面偏好保存在 App 用户目录的 language.json。手机网页使用同一翻译表，但语言可独立选择并记忆；原始运行日志和聊天内容不翻译，未知系统错误保留原始诊断信息。

外网访问在“网络访问 → 添加连接”添加并启用连接，可选择临时 HTTPS、已有穿透 / 反向代理、自有服务器 SSH 或 NAS 反代。桌面 App 已内置 cloudflared.exe，临时和固定 Cloudflare 隧道无需另行安装；复用旧 .local 时会查找其 bin/cloudflared.exe，旧单入口配置也会自动迁移为连接项。等待入口就绪并检查实际 HTTPS 地址，127.0.0.1 不是手机外网入口。默认保留账号密码保护。

未保存修改会在对应设置页的侧栏入口和底部保存栏显示小红点；切换页面仍保留提示，保存成功或改回原值后清除，保存失败时继续保留。

桌面 App 按系统和架构内置 cloudflared，首次使用临时或固定 Cloudflare 隧道无需额外安装。自定义程序路径和源码运行仍可在“应用与维护”检测或安装；内置版本随 App 更新。

手机扫码登录

1. 启动网关，在首页找到手机可达的连接地址。
2. 展开该地址下的 扫码登录。每个局域网、已就绪临时 HTTPS、已配置固定 HTTPS 地址都有独立区域，可以同时展开；默认收起。127.0.0.1 仅供电脑访问，不提供手机二维码。
3. 用手机相机扫描，在浏览器打开即可自动登录，无需输入密码。生成前会核对地址指向当前网关；无法连接或指向其他服务时不生成二维码。
4. 二维码 5 分钟内有效、仅可使用一次。收起、刷新会撤销旧码；网关重启后全部失效。过期或已使用会显示状态，可点击“刷新二维码”。浏览器登录有效期由“登录与设备”设置，默认 12 小时，0 表示不自动过期；网关重启保留登录。

固定域名、自有服务器和 NAS / Docker

在 网络访问 → 添加连接 中添加，填写后保存。每条配置可以命名、启用、停用或删除；局域网与临时 Cloudflare、多个自有服务器 / NAS 入口可同时启用。一个网关只需一个临时 Cloudflare 入口；同一 SSH 目标的不同配置须使用不同回环端口。正在运行时请先停止网关再改配置，保存后重新启动；不会自动更换原局域网端口。

| 方式 | 适用场景 | 首次配置 | | --- | --- | --- | | 仅局域网 | 手机与电脑在同一网络 | 保留局域网开关与端口 | | 临时 HTTPS | 无域名，愿意使用 Cloudflare | 添加连接、保存并启动；自动使用内置程序 | | 已有穿透 / 反向代理 | 已自行配置好到本机回环网关的 HTTPS 入口 | 只填手机 HTTPS 根地址（可含端口）；见配置指南 | | Cloudflare 固定隧道 | 有私人域名，没有服务器 | 在 Cloudflare 配置 DNS 与公开主机名，填写域名和 Tunnel Token | | 固定 HTTPS · Tailscale | 希望固定地址且不自建服务器 | 安装登录官方 Tailscale，检测地址并完成 Funnel/Serve 授权，见指引 | | 自有服务器 + SSH | 有 Linux 公网服务器；电脑在校园网或 NAT 后 | 准备 HTTPS 与转发权限，再填普通用户 SSH；域名需绑定公网 IP，留空使用 HTTPS 公网 IP 时须有匹配 IP 的受信任证书 | | NAS / 其他设备（已有穿透的高级选项） | NAS 已能访问电脑，已有域名和 HTTPS 反代 | 填固定 HTTPS 地址、NAS 可达的电脑 HTTP 地址；直接反代或导出 Nginx Docker 包 |

App 内可导出或复制配置参考（SSH 连接显示“导出手动配置参考”和“复制手动配置说明”，NAS 保留部署包入口）。生成的包带实际填写的地址、端口、中文步骤、验收项和启停命令，不含登录密码、Token、Codex 数据或 SSH 私钥。首次服务器部署完成后，日常只需打开 App 并启动网关；可启用“打开 App 时自动启动网关”。

本文使用 try2love 作为示例用户名，https://codex.try2love.com 作为示例地址，仅用于配置演示，不代表可访问的演示站点；请替换为自己的配置。

只有域名、没有服务器？ 阅读固定域名完整教程：从注册商修改 NS、创建 Cloudflare 隧道、填写 Token 到手机蜂窝网络验收，也包括常见错误排查。App 的 Cloudflare 连接卡片中可展开“首次配置”查看步骤。

自有服务器方案：手机 → 服务器 HTTPS → 服务器回环端口 → SSH → 电脑网关 → 原 Codex App。SSH 随网关启停、断线自动重试，不占用电脑 LAN 端口以外的新监听端口。支持密码、本地私钥（含口令）、SSH Agent 和已有 SSH 配置；新配置在 App 内核对主机指纹，指纹改变会拒绝连接。旧系统 SSH 别名继续兼容。密码和 Token 可保存在系统凭据存储，或仅在本次 App 内存中使用；不会写入普通配置或部署包。服务器需允许远程转发、保持回环绑定；自动证书方案需 DNS 指向服务器，80/443 可达且空闲。生成的 Caddy 包使用 Linux host 网络，不能直接用于 Mac/Windows Docker Desktop。已有反代占用 80/443 时，使用包内上游地址接入现有站点，无需启动新的 Caddy。

SSH 日常连接不要求 root。 使用普通用户（例如 try2love），按服务器 SSH 分步教程完成：① 手动准备 DNS、HTTPS 和转发权限；② App 保存配置并检查 SSH 登录；③ 启动连接、检测固定入口，再用手机蜂窝网络验收。

服务器软件安装、防火墙及 SSH 权限配置由用户或管理员手动完成。App 不接收 sudo 密码、不执行远端安装命令；已有网站接入原反向代理。SSH 登录通过只代表认证成功，不代表转发权限或公网入口已经可用。可导出或复制手动配置参考，其中的管理员命令须由用户自行执行。

只有私人域名时，选择 固定域名 · Cloudflare Tunnel：通常先将域名 DNS 托管到 Cloudflare（注册商不必迁移），创建隧道并添加公开主机名，如 codex.try2love.com → http://localhost:8787，在 App 保存域名和 Tunnel Token 后启动。Token 仅运行已有隧道，不自动创建 DNS；不需要公网服务器或电脑入站端口。建议独立子域名，不使用 /codex/ 路径。电脑、Codex App 和网关仍需在线。

NAS 方案：Docker 只部署 HTTP 入口，原电脑仍需保持唤醒并运行 Codex App 与网关。NAS 反代已有 HTTPS 时可直接转发到电脑，通常无需增加容器。跨网络且不互通时，仅填写域名无法连接，应选择服务器 SSH 方案或先准备可用 VPN 路由。详见 NAS 部署说明。

已有穿透 / 反向代理方案只保存公开 HTTPS 地址，穿透软件和证书由用户管理。上游须指向本机网关实际回环端口，保留公开 Host；可以关闭 LAN 与本机网页访问。跨设备 NAS 仍使用上表的进阶方式。安装页见图解步骤。

启动后点击 检测固定入口：核验 HTTPS 返回的是当前网关实例，而非其他服务。该检测从电脑发起，仍需手机关闭 Wi-Fi 后用蜂窝网络验证。所有启用的固定地址显示在首页。通知跳转地址留空时优先使用列表中第一个启用的固定地址，再选临时 HTTPS 或局域网；也可在通知设置中明确指定地址。域名和服务器费用由所选服务商决定，本项目不会代购或自动开通资源。

Cloudflare Tunnel 和 Tailscale 公网转发/中继可能经过境外节点，中国大陆直连可能较慢或超时；稳定的代理线路可能改善体验，实际速度以当前网络为准。Tailscale 私有组网可采用点对点连接，具体取决于网络条件。

额外 HTTPS 地址有什么用？

这是网关的 访问地址允许列表。只有已经在其他地方配置好反向代理或隧道、希望额外域名访问同一网关时，才需要填写，例如 https://codex.try2love.com，每行一个，不含路径。

填写域名不会建立隧道、配置 DNS 或申请证书。代理必须能到达电脑网关，并保留该域名的 Host 请求头。连接卡片中的固定域名会自动加入，不必重复填写；只用局域网或临时 Cloudflare 时留空即可。

中英文界面

电脑 App 顶部和手机网页 更多 → 显示设置 中有 Language / 语言 选择器，各自记住选择。无需重启网关；切换时保留未保存配置、消息草稿和待确认表单的输入。翻译仅覆盖界面文案，聊天原文、模型 / Skill 内容、命令和日志原文保持不变。部署 ZIP 同时包含中文和英文说明，“复制给部署 Agent”按当前界面语言生成。

配置第三方通知：Bark、ntfy 与 PushPlus

v2.1.3 支持配置多个 Webhook 接收目标：每个机器人可分别命名、启停、编辑、测试和删除，自定义 HTTPS 地址、请求头与 JSON 模板。旧版单个 Webhook 配置会保留，投递继续复用现有提醒策略、去重和重试。见 Webhook 配置说明。

直连网关后，从手机「外观与显示」、Web 设置或聊天列表底部进入 第三方通知，选择 Bark（iPhone）、ntfy（Android）或 PushPlus（微信），再进入对应配置页。英文入口显示 Push alerts。共享中继不开放此配置入口。

手机和 Web 与电脑端使用同一份网关配置。通道页面可启停、修改地址及主题、填写或清除密钥，保存后点击 测试已保存的配置；通用设置可调整通知跳转地址、是否显示聊天标题、安全事件及网关启动/入口变化通知。已保存的密钥不会返回手机页面，留空保留；更换服务地址时重新填写。测试以实际设备收到通知为准。

下面说明电脑端的 Bark、ntfy 配置；手机和 Web 可填写相同的服务信息。微信通道见 PushPlus 说明。

1. iPhone 推荐 Bark：安装 Bark 并允许通知，在电脑 App 的“消息通知 → Bark 推送”填写服务地址和 Device Key。例如手机展示 https://api.day.app/你的密钥，服务地址填 https://api.day.app，Device Key 只填密钥。也支持自建服务；手机须在对应服务器注册。密钥保存后默认遮罩显示，可点击眼睛图标查看；更换服务器须重新填写。参阅 Bark 官方说明。
2. Android 使用 ntfy：安装 ntfy 并允许系统通知、锁屏显示和后台运行。首次测试可用 https://ntfy.sh：点击“生成随机主题”，在手机 ntfy 订阅相同的服务和完整主题名，公共匿名主题的 Token 留空。主题自动创建，无需单独注册。匿名主题没有访问控制，知道名字的人可读写；使用随机长名称并保持聊天标题关闭。正式使用可选择受访问控制保护的主题，按服务要求填写 Token。
3. 启用需要的通道，保存配置，再分别点击“发送 Bark 测试通知”或“发送 ntfy 测试通知”，以手机实际收到为验收标准。两个通道可单独启用或同时开启，接收相同的会话提醒。此步骤无需启动网关；服务器接受请求不等于手机已经收到。
4. 启动网关，在网页 设置 → 全会话通知 分别选择请求处理通知和运行完毕通知。新配置默认开启请求处理通知、关闭运行完毕通知；必须先配置并开启至少一个推送通道。
5. 新出现的命令、文件、权限请求或提问会触发通知；点击通知回到该聊天，沿用网页登录与确认卡片。
6. 每个聊天的 提醒 中，两类通知均可选择 跟随全局设置、开启、关闭，彼此独立；升级时保留已有关注聊天的明确选择。完成通知从首次实时连接建立边界，失败、手动停止和开启前已结束的历史不触发。
7. 电脑 App 的 “消息通知 → 已关注聊天” 显示会话名称、所在设备、目录与会话 ID，可直接切换完成通知或 “删除监控”，操作即时保存。删除监控停止该会话的提醒，不删除会话；全局默认与单会话覆盖在网页设置或聊天提醒中管理。网关停止或通知通道关闭时，也可管理已保存的监控。远程会话显示最近获取的名称，尚未获取时保留设备和会话 ID。

通知跳转地址留空时优先使用已配置的固定 HTTPS 入口，再选临时 HTTPS 或局域网地址；手动填写的通知地址始终优先。临时域名变更不会改变 ntfy 订阅，但旧通知中的旧链接可能失效。Android 后台接收受系统电池与网络设置影响。参阅 ntfy 手机说明。

网关启动与入口通知

新配置默认开启地址通知，升级保留已保存的关闭选择。在电脑 App 的 消息通知 → 网关启动与入口通知 可设置“每次启动网关及入口变化时发送地址”，可填写网关名称。先启用至少一个 PushPlus、Bark 或 ntfy 通道并保存配置，再启动网关、点击“发送当前入口测试通知”，确认手机收到。

每次启动网关都会汇总发送已启用的访问地址，即使地址未变。包括局域网、NAS / 已有反代固定域名、自有服务器（SSH 转发建立后）和临时 HTTPS（隧道就绪后）；稍晚就绪的入口和地址变化会补发更新。关闭的网卡、关闭的入口和回环地址不在通知中。局域网链接需同一网络，固定域名需要先完成部署。

此开关与聊天提醒独立，新配置默认开启，升级保留原有选择。通知使用当前入口，忽略聊天通知的固定跳转地址，不包含密码或登录令牌；各通道分别重试，停止网关或关闭开关后停止新的发送。升级到 v1.3.2 或后续版本后请先配置并实测，再依靠通知获取后续重启的新入口；旧版本尚不具备此功能。

从源码运行与打包

开发环境需要 Node.js 与 Python；只有构建时需要 Electron、electron-builder 和 PyInstaller。Windows 与 Mac 应分别在目标系统上构建，Python、Node.js 与安装包的 CPU 架构必须一致。

macOS 在构建网关运行时后执行 npm run build:mac -- --arm64（M 系列）或 npm run build:mac -- --x64（Intel），在 dist/desktop/ 生成对应架构的 DMG 和 ZIP。DMG 用于拖入“应用程序”安装；ZIP 用于应用内更新。切换架构时须先用对应架构的 Python 重新执行 scripts/build-desktop.py。CI 分别使用 Apple Silicon 和 Intel Mac 构建并验证完整安装包。

git switch main
npm ci
npm run desktop

构建步骤（在当前项目的 Python 虚拟环境中执行）：

python -m pip install -r requirements-desktop.txt
python scripts/build-desktop.py
npm run pack:desktop

Windows 可再执行 npm run build:windows 生成安装包与 ZIP；文件位于 dist/desktop/。随后执行 npm run test:windows-app 验证实际打包窗口、内置运行时、托盘恢复与启停。此检查使用临时端口和合成数据，不发送模型请求或真实通知，需要可显示窗口的 Windows 会话和 Node.js 24。开发测试可用 CMB_DATA_DIR 指定独立数据目录，CMB_PYTHON 指定开发用 Python；打包后的 App 使用内置运行时。运行 python -B -m unittest discover -s tests -v 和 npm run test:desktop 进行自动检查。产品图标源为 assets/icon.png，可用 npm run icons:desktop 更新桌面 PNG/ICO、手机网页和介绍页图标。macOS 打包时会从桌面 PNG 生成系统图标。

App 设置界面通过本机进程通信管理网关；网关启停、更新及访问范围配置不对局域网或隧道开放；默认关闭的网络恢复开关允许已认证的直连客户端修改，并校验 CSRF。直连网关的网页登录用户可以修改 Bark、ntfy、PushPlus 及通用通知配置，沿用 Host、Origin、登录与 CSRF 校验；共享中继不开放这些配置入口。配置、通知密钥、凭据和投递记录位于网关数据目录，三个推送通道默认关闭；打包与提交不包含 .local、.tmp 或个人配置。

Codex 会话功能

| 功能 | 说明 | | --- | --- | | 新建聊天 | 在当前客户端创建；Codex 可选择本机/SSH 项目，或不选项目，创建本身不调用模型 | | 同步 App 聊天 | 读取已有聊天、历史、实时回复和工具输出 | | Markdown 与公式 | 标题、列表、引用、表格、代码块及 LaTeX 公式；资源与字体本地提供，无需 CDN | | 渐进加载 | 先显示最近 20 条，后台补齐到 100 条；上翻至顶部附近自动再读 100 条，工具正文按需展开 | | 同一会话执行 | 发送新消息、补充当前任务、排队、撤回待发送消息、停止任务 | | 上传附件 | 多选文件或图片，随消息发送到原会话，支持排队和补充任务 | | 手机回应 | 支持命令、文件、临时权限请求及提问卡片；复杂请求提示回到桌面处理 | | SSH 会话 | 显示桌面 App 已连接主机的聊天，操作继续交给对应主机的会话 | | 聊天列表 | 最近交互或项目视图、主机标签、运行中与完成未查看标识 | | 模型设置 | 更改当前聊天的模型与推理强度，支持自定义模型 ID；符合原生模型目录与工作区条件的接入可开关 Fast 模式 | | 计划与目标模式 | 从网页开启计划或原生目标；计划完成后可直接执行或继续修改 | | Skill | 按会话所在主机与工作目录读取已安装技能，搜索后随消息发送原生 Skill 引用 | | 登录方式 | 独立账号密码；可配置免密 | | 连接方式 | 局域网、临时 Cloudflare 与多个固定 HTTPS 入口可并行；配置可添加、命名、启停和删除 | | 双语界面 | 电脑 App 与手机网页支持简体中文 / English 切换 | | 响应压缩 | 支持 gzip，减少大聊天通过外网传输的数据量 | | 文件与图片 | 项目文件预览、目录定位、图片缩放与可暂停下载；普通下载阈值可实时配置 |

默认继承桌面会话的模型、provider 和权限策略。手动切换模型时更新模型与推理强度；只有主动切换 Fast 开关才更新速度设置。模型是否可用取决于当前 provider。

阅读长聊天

打开聊天后先显示最近 20 条，再在后台补齐最近 100 条。上翻至距已加载内容顶部约 10 条时，自动读取更早的 100 条；也可点击“查看更早内容”。加载失败可在顶部重试，补入历史时保留当前阅读位置。

工具调用与结果合为活动记录，展开时才读取正文。超长回复和日志分段读取，点击“继续加载正文”可继续阅读；单页同时受条数和体积限制，因此内容很长时可能分多次补齐。正在生成的回复更新原消息；阅读旧内容时显示“有新内容”或“有待确认请求”入口。

实时同步通过增量长轮询传递变化，不重复传输整段聊天。桌面重新提供不同历史快照或网关重启时，过期游标会触发重新同步最近内容。电脑端仍保留完整会话上下文。

运行要求

• macOS、Windows 10/11 或实验性 Ubuntu；安装需要使用的桌面客户端并完成配置。Claude 自动接入仅支持 macOS/Windows。
• 使用发布的桌面 App 时无需安装 Python 或 Node.js，网关运行时已内置。
• 仅从源码或命令行运行时需要 Python 3.9+；网关本身只使用 Python 标准库，无需 pip install 或前端构建。Windows 使用原生 CPython，无需 WSL。桌面 App 的开发与打包另需 Node.js 及构建依赖。
• 电脑保持唤醒、联网，网关进程保持运行。
• 使用 SSH 聊天时：App 中已配置该主机，电脑上相应 SSH 别名可非交互连接，远端有 Python 3。Windows 需要 PATH 中可用的 OpenSSH ssh.exe。模型/Skill 目录还需要远端可用的 Codex 运行时。
• 外网隧道：桌面构建内置 cloudflared，源码运行可自行安装；二进制在构建时按锁定版本和 SHA-256 获取，不提交到仓库。源码使用新 SSH 配置或系统凭据存储时，需安装 requirements-desktop.txt 中相应依赖。

命令行启动：局域网（进阶）

已下载桌面 App 的用户无需执行本节命令。以下适用于希望从源码启动网关的用户。

Windows

在 PowerShell 中执行：

```powershell git clone https://github.com/try2love/codex-mobile-

... (README truncated for length)