This reference covers remote connections, device permissions, notification requirements and troubleshooting.
Connecting an iPhone, iPad or browser for the first time? Follow Get connected, then use the device guide for everyday controls and sharing.
Server platforms
Pair with a macOS or Linux host running gtmux. The server list, routes, sharing, terminal/chat and HQ use that host’s state. Linux does not offer desktop window focus or lid controls.
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.
Message delivery
After sending, the temporary chat bubble distinguishes Sending from Sent to terminal. The latter confirms terminal delivery, not that the agent has read or finished it. The bubble is removed when a new matching prompt reaches the transcript, even if later turns arrive in the same refresh; it does not reappear as the conversation advances.
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.
Usage widgets
iOS/iPadOS 17+ supports Home Screen and Lock Screen usage widgets. They follow the current owner server and show provider quota or balances with reading times. See usage widgets for setup, refresh limits, privacy and macOS scope.
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.
All panes
In All panes, the vertical expand/compress button matches the Mac pane browser. Tap the magnifying glass to focus search; session names, commands, directories and pane/window IDs are searchable.
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. - “Share access has expired”: the pane grants belong to a previous tmux server. Ask the owner to grant access to the intended panes again. Web, phone and iPad keep the guest connection and show this explanation; pairing again does not restore these grants. An ordinary empty shared radar does not mean access has expired.
- 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.
HTTP 304 means the conversation has not changed; the app keeps its cached content. It is not a connection failure. Older 304 warnings remain in raw exports but appear as Content unchanged, outside the problems filter. Leaving a page cancels its read without adding a network warning. App-imposed deadlines are recorded as timeouts; other Request did not complete entries mean no response arrived, not that the whole Mac was offline. Compare their timestamps with later successful reads and the Mac’s bundle.
Review server access
Open Settings → Manage server → Access history to inspect device/browser requests and HTTP results in a compact log. Local times include seconds, dates follow the app language, and full identity/source metadata is visible without expanding rows. This is owner-only; guest links cannot read it. Refresh starts at the newest records; Load earlier keeps the current list. An old server must be updated before it supports history. Details about sampling, private storage and permission limits are in Server access history.
In Access history, choose Logs or Devices. Filter by a full pairing ID, operation or outcome; selecting a device summary opens that device’s log. Clear broadens the view. Continue summary reads earlier pages when the total is still partial. Counts describe recorded activity: successful reads are sampled, and device names do not identify a unique pairing. Older servers must be updated for filtering/grouping.
For the Standard client version floor, update channel and connector restart, see security updates.
Trace records
Open a session’s wrench menu and choose Trace to inspect loaded messages and recorded tool calls. Search and type/session filters cover the loaded history. On iPhone, select a record and close its details to return to the same list; a wide iPad keeps both columns visible. Closing details expands the list. Copy uses the original text; new content waits for Update details. Use Follow latest to return to current activity. Closing Trace keeps your conversation or terminal and its unsent draft. The same tool is available in HQ and readable external conversations; external sessions stay read-only.
Trace shows recorded inputs and summaries. It cannot supply absent tool outputs, model request timing or token usage. The disclosure About these records explains this scope.
Source: docs/phone.md at fb03cff · Edit on GitHub
本页说明远程连接方式、设备权限、通知条件和连接故障的排查方法。
第一次连接 iPhone、iPad 或浏览器？ 先按首页连接步骤配对，再看设备操作指南。
服务器平台
可配对运行 gtmux 的 macOS 或 Linux 主机。服务器列表、线路、分享、终端／对话和 HQ 都读取所选主机的数据。Linux 不提供桌面窗口跳转、合盖控制。
连接方式
实时雷达和终端需要能连接到运行 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。
消息发送状态
发送后的临时气泡会区分“正在发送”和“已发送到终端”。后者表示终端已接收，不代表 agent 已阅读或执行。对话记录出现本次输入后，临时气泡会移除；即使同一次刷新已有后续对话，也不会再次出现。
在线与通知条件
Mac 必须保持唤醒，才能远程访问。MacBook 合盖默认休眠；gtmux awake on 可让它合盖后继续运行，但不会替你启动 serve 或隧道。电池电量到 30% 时提醒，20% 时恢复休眠。
推送不要求手机直接连接 Mac。它需要醒着、运行 serve 且能访问推送中继的 Mac，以及完成注册、能接收 Apple 推送的 iOS 设备。网络和通知设置可能延迟或阻止送达。实时雷达和回复仍需要能连到 Mac。
tmux 外的 agent 只读：没有 pane，就没有可发送输入的地方。
用量小组件
iOS/iPadOS 17 及以上支持主屏幕和锁屏用量组件，跟随当前拥有完整访问权限的 服务器，显示服务商额度或余额及读数时间。添加方法、刷新限制、隐私和 macOS 支持范围见用量小组件。
HQ 快捷入口
在手机雷达中，长按 HQ 浮窗即可选择「用量」或「知识库」。点按进入 HQ，拖动调整位置。 HQ 启动后提供快捷菜单；尚未启动时，浮窗说明如何在 Mac 上启动。iPad 紧凑窗口使用 同一浮窗，常驻侧栏仍通过 HQ 页的入口打开这些页面。
桌面应用会话
ChatGPT 桌面版 Codex 会话显示在「桌面应用」，默认标记为「仅显示状态」。 它们不计入管理总数、HQ 待处理、通知或实时活动；对话内容也不进入摘要和知识采集。
在已配对的手机或 iPad 上，点击会话即可查看实时更新的只读对话，查看不会开启 HQ 跟进。 在长按菜单中选择「跟进设置」，可允许 HQ 读取、分析和汇报。开关修改自动保存， 点击「完成」关闭。「会话通知」和「知识留存」需分别开启，初始均为关闭，HQ 跟进 开启前不可操作；知识采集仅覆盖后续活动。
Mac 确认当前设置后才更新列表标记。发生冲突或回执丢失时，会重新读取实际设置； 读取失败则需「重新加载」成功后再修改。关闭「HQ 跟进」同时关闭两项额外权限，保留 已有记录。再次开启不会自动恢复权限。设置仅对当前 Mac 的这段会话生效，不会扩展到 其他桌面会话或其他 Mac。需处理的问题仍在 ChatGPT 桌面版继续；这些设置不提供终端 输入或批准操作。旧版 Mac 核心需更新后才能提供设置入口；访客没有桌面会话跟进控制。
所有 pane
「所有 pane」的展开／折叠图标与菜单栏一致。点击放大镜即可搜索会话、命令、目录和 pane／window ID。
排查连接问题
- 同一个 Wi-Fi 也连不上： 在设备浏览器里测试
http://<mac-ip>:8765/api/health。打不开时检查网络路径，或改用隧道／VPN。 - 配对码被拒绝： 已使用的码不能再用，每台设备生成新码。
- 访客能看不能输入： 检查链接的输入范围，以及
gtmux share on总开关。 - “分享授权已失效”： pane 授权对应的是重启前的 tmux，请联系所有者重新授权需要访问的 pane。Web、手机和 iPad 会保留访客连接并说明原因；重新配对不会恢复这些授权。普通的共享空列表不代表授权失效。
- 收不到通知： 检查 Mac 是否醒着、serve 是否运行、设备是否注册，以及 iOS 通知权限。
app 的「设置 → 诊断」可导出本地连接和配对记录；gtmux doctor --bundle 收集 Mac 一侧的信息。协议细节见 API contract。
HTTP 304 表示对话未变化，app 会保留已有内容，并非连接失败。旧版记录中的 304 会显示为「内容未变化」，不计入问题；导出的原始记录保留。退出页面时取消读取不再 产生网络告警。app 的请求时限到期会明确标为超时；「请求未完成」仅表示该次未收到 响应，不能据此认定整台 Mac 离线。排障时请对照后续成功请求的时间及 Mac 侧诊断包。
查看服务器访问记录
打开设置 → 管理服务器 → 访问历史，按日期查看紧凑的设备与浏览器访问日志。本地时间精确到秒，日期跟随 App 语言；完整设备标识、来源与 HTTP 结果直接可见，无需逐条展开。仅所有者可用，访客链接不能读取。刷新从最新记录开始，载入更早记录会保留当前列表。旧服务器需要更新后才支持历史。采样、私有存储及权限边界见服务器访问历史。
访问历史可切换日志与设备汇总，按完整配对 ID、操作或结果筛选。点击汇总设备进入对应日志，清除筛选可扩大范围；显示部分结果时，可继续读取更早记录。计数是已记录活动，读取经过采样；同名设备仍按不同配对 ID 区分。旧服务器需升级才能筛选及汇总。
Standard 客户端的安全版本、更新渠道及连接进程重启说明见安全更新。
查看轨迹
在会话的扳手菜单中选择“轨迹”，查看已加载消息和调用记录。搜索、类型和会话筛选覆盖 已加载历史。iPhone 点入一条记录，关闭详情后回到原列表；宽屏 iPad 可同时显示列表与 详情，关闭详情后列表恢复全宽。复制使用原始文字，新内容需点击“更新详情”才会替换。 “跟随最新”可回到当前进度。关闭轨迹会保留对话或终端及未发送草稿。HQ 和可读的外部 会话也使用此工具；外部会话仍是只读。
轨迹展示已记录的参数与摘要，不能补出缺失的工具输出、模型请求耗时或 Token 用量。 “记录范围”默认收起，可按需查看说明。
来源：docs/phone.zh.md（fb03cff）· 在 GitHub 上编辑