Connection methods, device permissions and notification requirements.
Connecting an iPhone, iPad or browser for the first time? Follow Use your phone, iPad and browser for setup, daily use and sharing.
Connection methods
The live radar and terminal need a reachable Mac running gtmux serve. The Mac opens
outbound tunnels, so no inbound port forwarding is needed.
| Method | When to use it | Address and requirements |
|---|---|---|
| Local network | Devices can reach each other on the same network | Mac address, normally port 8765 |
| Standard tunnel | Access from other networks | Free, stable https://gtmux-<label>.ccy.dev; uses cloudflared on the Mac |
| Direct tunnel | The network blocks Standard | Paid access code; port 443 through gtmux’s server; no cloudflared needed |
| Quick tunnel | A temporary connection | trycloudflare.com address changes on every run; devices must pair again |
| Tailscale or another VPN | You already connect your devices through a VPN | Reachable VPN address, normally port 8765 |
A tunnel still needs both networks to allow the connection. Corporate or guest Wi-Fi may isolate devices even when they use the same Wi-Fi name.
Tunnel settings
gtmux tunnel defaults to Standard and reuses an active always-on tunnel.
--service keeps it running across reboots; --unservice removes the service;
--status shows the active method and address. If Direct is already active,
--service keeps Direct. Use --backend cloudflare explicitly to switch to Standard.
With an updated gtmux, always-on Standard access recovers automatically when a tunnel
is deleted or reclaimed after a long absence. Your saved address and phone/iPad pairings
stay the same. To request recovery now: gtmux tunnel --backend cloudflare --service --recover --yes.
In the Mac Preferences or Pair your phone window, a failed route lookup offers Retry. Reopening either window refreshes the list when Direct is active. If a refresh fails, the previous routes and measurement time remain visible; a list error alone does not mean the active tunnel has disconnected.
Direct is unlocked at gtmux Direct, then redeemed
with gtmux tunnel --redeem <code>. One code covers up to three Macs; each gets its own
address and account. --servers lists routes and measured latency; --server <id> moves
a Mac while keeping its code and port. Devices that have connected before follow the
move; devices that only paired must scan again. Existing guest links stop working.
Full flags: gtmux tunnel.
Self-hosting: the tunnel design and deploy/self-tunnel/.
Pairing and guest permissions
Pairing gives each of your devices an owner credential. It can read and type into panes, manage guest links and create new pairing codes. Treat that credential as a password.
A pairing code works once and expires in five minutes. Generate a fresh code for each device. If the address changes before enrollment, refresh the code. After successful enrollment, a failed first radar load only needs a connection retry.
Guest links grant access to specified panes. --view permits reading; --type permits
input and also adds the pane to view. Input additionally requires the master switch
gtmux share on. --expires accepts values such as 45m, 24h or 7d; without it,
the link does not expire. Revoking a link refuses its next request.
Guests cannot access the HQ page, owner settings, push registration, session creation or
gtmux attach. A guest who can type uses the permissions of the program in that pane:
pane scope does not sandbox its filesystem or network access.
Revoke a lost device on the Mac with gtmux devices revoke <id>. The phone’s UI does
not revoke owner devices or switch remote access on and off; those limits do not
restrict what its owner credential can do. Never publish pairing codes, device
credentials or guest links. A public tunnel address alone does not grant access.
Full flags: gtmux pair,
gtmux share and
gtmux devices.
Availability and notifications
The Mac must remain awake for remote access. A closed MacBook normally sleeps;
gtmux awake on keeps it running with the lid shut, but does not start serve or the
tunnel. On battery, it warns at 30% and restores sleep at 20%.
Notifications do not need a direct phone-to-Mac connection. They need an awake Mac running serve with access to its push relay, a registered iOS device and Apple’s push service. Notification settings and network conditions can delay or block delivery. The live radar and replies still need a connection to the Mac.
Agents outside tmux are read-only: without a pane, there is nowhere to send input.
HQ shortcuts
On the phone radar, hold the floating HQ button and choose Usage or Knowledge base. A tap opens HQ; dragging moves the button. Shortcuts are available when HQ is running; if it has not started, the button explains how to start it on the Mac. Compact iPad windows use the same button; the iPad sidebar keeps the resource entrances on the HQ page.
Desktop conversations
ChatGPT desktop Codex conversations appear in Desktop apps, initially marked Status only. They do not affect managed totals, HQ attention, push notifications or Live Activity, and their conversation content is excluded from digest and mining.
On a paired phone or iPad, tap a conversation to read its live-updating Chat. Viewing it does not enable HQ follow. Choose Follow settings from its long-press menu to allow HQ reading, analysis and progress reports. Switches save automatically; use Done to close. Conversation notifications and Save to knowledge base are independent choices, initially off and unavailable until HQ follow is on. Knowledge capture covers future activity, not earlier messages.
The list badge updates only after the Mac confirms the current settings. A conflict or missing save receipt triggers a fresh read; if that fails, use Reload before making more changes. Turning off HQ follow also clears both optional permissions and keeps existing records. Re-enabling follow does not restore the optional permissions. Settings apply to this conversation on this Mac, not every desktop conversation or another Mac. Continue conversations in ChatGPT desktop: these settings do not enable terminal input or approval from gtmux. An older Mac core needs updating to expose settings. Guests have no desktop follow controls.
Troubleshooting
- Cannot connect on the same Wi-Fi: test
http://<mac-ip>:8765/api/healthfrom the device. If it cannot load, check the network path or use a tunnel/VPN. - A used pairing code is refused: generate a new code; each enrolls one device.
- A guest can see but cannot type: check the link’s input panes and
gtmux share on. - No notifications: check the Mac is awake, serve is running, the device is registered and iOS allows notifications.
The app’s Settings → Diagnostics exports its local connection and pairing log.
gtmux doctor --bundle collects the Mac side. Protocol details: API contract.
Source: docs/phone.md at v1.0.114 · Edit on GitHub
连接方式、设备权限与通知条件。
第一次连接 iPhone、iPad 或浏览器？ 从用手机、iPad 和浏览器管理开始，按步骤完成配对、日常操作和分享。
连接方式
实时雷达和终端需要能连接到运行 gtmux serve 的 Mac。隧道由 Mac 主动向外建立，不用开放入站端口。
| 方式 | 适用情况 | 地址与要求 |
|---|---|---|
| 局域网 | 同一网络内，设备之间能互相访问 | Mac 的地址，默认端口 8765 |
| Standard 标准隧道 | 跨网络访问 | 免费、固定的 https://gtmux-<label>.ccy.dev；Mac 使用 cloudflared |
| Direct 直连隧道 | 网络拦截标准隧道 | 访问码付费解锁，经 gtmux 服务器的 443 端口；不需要 cloudflared |
| 临时隧道 | 临时连接 | trycloudflare.com 地址每次运行都变，需要重新配对 |
| Tailscale 或其他 VPN | 设备之间已有 VPN | 能访问的 VPN 地址，默认端口 8765 |
隧道仍需两端网络允许连接。公司或访客 Wi-Fi 即使名称相同，也可能隔离设备。
隧道设置
gtmux tunnel 默认使用 Standard，已有常驻隧道时直接复用。--service 注册为后台服务，重启后继续运行；--unservice 移除服务；--status 显示当前方式和地址。Direct 已开启时，--service 会保留 Direct；切回 Standard 要明确指定 --backend cloudflare。
更新后的 gtmux 会自动恢复常驻 Standard 连接，包括之前被误删、或长期离线后被回收的隧道。
原地址和手机/iPad 配对保留。也可立即执行 gtmux tunnel --backend cloudflare --service --recover --yes。
Mac 偏好设置和配对窗口在线路加载失败时提供「重试」；直连开启时，重新打开窗口也会刷新线路。刷新失败会保留上次的线路列表和测量时间，列表加载失败不等于当前隧道已断开。
Direct 在 gtmux Direct 获取访问码，再用 gtmux tunnel --redeem <码> 兑换。一个码最多用于三台 Mac，每台有独立地址和账号。--servers 列出服务器和实测延迟，--server <id> 切换服务器，码和端口不变。此前已连接过的设备会跟随切换；只配对、未连接过的设备需重新扫码，原访客链接也会失效。
完整参数：gtmux tunnel。自托管见隧道设计和 deploy/self-tunnel/。
配对与访客权限
配对为你的设备生成独立 owner 凭据，可查看和输入 pane、管理访客链接、签发新配对码。这个凭据应当作密码保管。
配对码只能使用一次，五分钟过期，每台设备需生成新码。配对前地址发生变化，要刷新配对码；已经配对成功但首次雷达加载失败，只需重试连接。
访客链接只授权指定 pane。--view 允许查看，--type 允许输入，也会自动加入可见范围。输入还需总开关 gtmux share on。--expires 可写 45m、24h 或 7d；不写则不过期。吊销链接后，下一个请求会被拒绝。
访客不能访问 HQ 页面、owner 设置、推送注册、新建会话或 gtmux attach。能输入的访客使用 pane 内程序的权限；pane 范围不限制程序对文件和网络的访问。
设备丢失后，在 Mac 上用 gtmux devices revoke <id> 吊销。手机界面不提供吊销 owner 设备和开关远程访问，但这些界面限制不约束 owner 凭据的能力。不要公开配对码、设备凭据或访客链接；只有公网地址并不授予访问权限。
完整参数：gtmux pair、gtmux share和 gtmux devices。
在线与通知条件
Mac 必须保持唤醒，才能远程访问。MacBook 合盖默认休眠；gtmux awake on 可让它合盖后继续运行，但不会替你启动 serve 或隧道。电池电量到 30% 时提醒，20% 时恢复休眠。
推送不要求手机直接连接 Mac。它需要醒着、运行 serve 且能访问推送中继的 Mac，以及完成注册、能接收 Apple 推送的 iOS 设备。网络和通知设置可能延迟或阻止送达。实时雷达和回复仍需要能连到 Mac。
tmux 外的 agent 只读：没有 pane，就没有可发送输入的地方。
HQ 快捷入口
在手机雷达中，长按 HQ 浮窗即可选择「用量」或「知识库」。点按进入 HQ，拖动调整位置。 HQ 启动后提供快捷菜单；尚未启动时，浮窗说明如何在 Mac 上启动。iPad 紧凑窗口使用 同一浮窗，常驻侧栏仍通过 HQ 页的入口打开这些页面。
桌面应用会话
ChatGPT 桌面版 Codex 会话显示在「桌面应用」，默认标记为「仅显示状态」。 它们不计入管理总数、HQ 待处理、通知或实时活动；对话内容也不进入摘要和知识采集。
在已配对的手机或 iPad 上，点击会话即可查看实时更新的只读对话，查看不会开启 HQ 跟进。 在长按菜单中选择「跟进设置」，可允许 HQ 读取、分析和汇报。开关修改自动保存， 点击「完成」关闭。「会话通知」和「知识留存」需分别开启，初始均为关闭，HQ 跟进 开启前不可操作；知识采集仅覆盖后续活动。
Mac 确认当前设置后才更新列表标记。发生冲突或回执丢失时，会重新读取实际设置； 读取失败则需「重新加载」成功后再修改。关闭「HQ 跟进」同时关闭两项额外权限，保留 已有记录。再次开启不会自动恢复权限。设置仅对当前 Mac 的这段会话生效，不会扩展到 其他桌面会话或其他 Mac。需处理的问题仍在 ChatGPT 桌面版继续；这些设置不提供终端 输入或批准操作。旧版 Mac 核心需更新后才能提供设置入口；访客没有桌面会话跟进控制。
排查连接问题
- 同一个 Wi-Fi 也连不上： 在设备浏览器里测试
http://<mac-ip>:8765/api/health。打不开时检查网络路径，或改用隧道／VPN。 - 配对码被拒绝： 已使用的码不能再用，每台设备生成新码。
- 访客能看不能输入： 检查链接的输入范围，以及
gtmux share on总开关。 - 收不到通知： 检查 Mac 是否醒着、serve 是否运行、设备是否注册，以及 iOS 通知权限。
app 的「设置 → 诊断」可导出本地连接和配对记录；gtmux doctor --bundle 收集 Mac 一侧的信息。协议细节见 API contract。
来源：docs/phone.zh.md（v1.0.114）· 在 GitHub 上编辑