常见问题与获取帮助

遇到问题时先在本页找答案，再按“排障入口”定位到对应主题的诊断步骤；仍无法解决时按 获取帮助 反馈。功能说明见 使用指南，文档全集见 文档中心。

常见问题

重启服务后会话去哪了？

会话、PTY 和缓冲只保存在内存中，服务重启即结束所有会话。这是有意的设计边界：WebMux 不使用数据库、不做守护进程分离，也不与 tmux 互通。只有显式登记的状态文件（仓库清单、启动配置、偏好等，见 持久化清单）会持久保存，会话本身不会。

例外是 混合会话：WebMux 记录它与 agent 会话的对应关系，重启后可从首页“可恢复”分组恢复，对话本身由 agent 保存。

创建会话时找不到 claude / codex？

systemd 和 launchd 不会加载你的交互 shell 配置。可在自定义启动配置中显式使用 bash -ic 'exec opencode "$@"' opencode 来加载 ~/.bashrc 中的 PATH 和环境变量，或把程序目录加入服务的 PATH，参见 agent 的 PATH。

两台设备同时打开同一会话，布局互相影响？

两端共享同一个 PTY，但只有控制端决定终端尺寸：先打开的设备控制，后打开的设备观察（按原网格显示、可平移）。在观察端输入或点击“接管控制”即可切换。

粘贴 / 复制没有权限？

HTTP 不是浏览器安全上下文，Clipboard API 不可用。WebMux 会回退到文本框手动粘贴 / 复制；也可以通过 tailscale serve 或 Caddy 提供 HTTPS，见 HTTPS。

重连后首行有少量乱码？

缓冲按字节环形存储，最旧的数据可能从多字节字符或转义序列中间开始，属于设计允许范围。

忘了 Token，或者浏览器提示需要登录？

首次启动生成的 token 持久化在配置文件中，可用 webmux status --json --reveal-token 查看，或用 webmux config path 找到配置文件。详见 配置。

升级后会话都没了？

升级需要重启服务，重启会结束所有终端会话。升级前先让 agent 告一段落，见 升级。

排障入口

• 安装、升级与服务状态：持久化升级与诊断、服务管理命令。
• 平台行为差异（Linux / macOS / WSL）：平台差异。
• Windows 托盘与 WSL：localhost 转发诊断、Token 与剪贴板。
• 公网入口：Cloudflare Tunnel 故障排查、Tailscale 手工移除与排错。
• 手机推送收不到：手机推送（Web Push）。
• 混合会话无法切换到聊天：开启条件、注意事项。
• agent 没有触发“需要你介入”提醒：需要你介入的提醒。

获取帮助

• 提问或报告缺陷：在 GitHub Issues 新建 issue，附上 webmux version、操作系统、浏览器与复现步骤。
• 不要公开安全漏洞：按 安全策略 私下报告。
• 日志：用户服务可用 webmux service logs -f 查看；日志不包含终端输入输出，但请在粘贴前检查是否含有路径等隐私信息。
• 想参与修复：从 参与贡献 开始。