使用文档

AgentMux 是什么#

AgentMux 是一个桌面应用，用来运维在远程主机与本机上执行的 AI 编程 Agent—— Claude Code、Codex、Gemini CLI、OpenCode、Aider、Cursor CLI 等。它的核心机制只有一句话：

它是单个二进制：没有服务端、没有守护进程、不需要注册账号。全部状态是应用数据目录下的 一个 SQLite 文件。每台远程主机只建立一条 SSH 连接并复用——终端、命令、文件传输都是这条 连接上的 channel，对同一台主机开十个终端也只认证一次；空闲连接十分钟后自动关闭。

环境要求#

运行 AgentMux 的电脑

被管理的主机

• 远程类 Unix 主机（Linux / macOS）：POSIX shell、tmux、一个 SSH 账号。缺 tmux 不要紧——AgentMux 的安装面板可以代装。
• 远程 Windows 主机：启用 OpenSSH Server 即可。那里没有 tmux——会话由 AgentMux 自带的守护进程托管：首次使用时经 SFTP 自动部署，协议走 SSH 端口转发，从不经过远端 shell。
• 屏幕专用主机：只想看不想操作的机器，一个开着 RDP 或 VNC 的地址即可——不需要 SSH，也没有任何凭据要预先保存（见主机运维 → 屏幕专用主机）。
• 本机（Linux / macOS）：只需要本地装有 tmux，无需 sshd、无需凭据。
• 本机（Windows）：同一台电脑提供两种主机——WSL 发行版（tmux 所在之处），以及原生 Windows（PowerShell、Windows 路径与工具链，适合 MSVC 构建、WPF、运行刚编译出的 .exe）。原生会话由 AgentMux 内置的会话守护进程托管，关窗口同样不会停掉工作。

可选：编排器与语义检索

本地编排与记忆的语义检索需要 Ollama， 外加一个对话模型和一个 embedding 模型。不装 Ollama，应用的其余全部功能完整可用——它只影响这两项。

安装#

每个 Release 提供三个平台的构建，由 GitHub Actions 从打了 tag 的 commit 产出，附带 .sha256 校验和。 构建暂未做代码签名与公证（分别需要 Apple 开发者账号与微软证书），因此首次打开各平台多一步确认。

macOS

1. 下载 agentmux-macos-universal.zip，解压后把 AgentMux.app 拖入「应用程序」文件夹。
2. 首次打开按系统版本处理未签名提示（见下表）。
3. 之后即可正常双击打开。

Windows

1. 下载 agentmux-windows-amd64.zip 并解压，其中包含 agentmux.exe 与安装脚本。
2. 直接双击运行即可；SmartScreen 弹窗时选择「更多信息」→「仍要运行」。
3. 如需正式安装（装到 %LOCALAPPDATA%\Programs\AgentMux、创建桌面与开始菜单快捷方式、不需要管理员权限），在解压目录执行：

powershell -ExecutionPolicy Bypass -File install-windows.ps1

卸载用同一脚本加 -Uninstall 参数，不会动 %APPDATA%\AgentMux 里的数据。

Linux

1. 先装运行时依赖：Debian/Ubuntu 执行 sudo apt install libwebkit2gtk-4.1-0；Fedora 执行 sudo dnf install webkit2gtk4.1。
2. 下载 agentmux-linux-amd64.tar.gz 并解压，包内含二进制、图标、.desktop 条目与 install.sh。
3. 运行 ./install.sh 完成安装，或直接执行二进制。

校验下载

# 每个文件都附带 .sha256，下载后比对：
shasum -a 256 -c agentmux-macos-universal.zip.sha256   # macOS
sha256sum -c agentmux-linux-amd64.tar.gz.sha256        # Linux

服务器版（无头）

同一个应用还有一份完全静态的无头构建：agentmux-server-linux-amd64.tar.gz 与 agentmux-server-linux-arm64.tar.gz。它不链接 GTK/WebKit，不需要图形界面，在任何 Linux 服务器上 直接运行即可对外提供完整的 Web 应用。推荐用一行安装脚本部署（含 systemd 服务与自更新）， 见无头服务器一节。

Android

1. 下载 agentmux-android.apk（Android 8.0+ · arm64），在手机或平板上安装——需要允许「安装未知来源应用」。
2. 首次打开会由前台服务拉起内嵌的核心，随后 WebView 连本机 127.0.0.1，无需任何服务端。
3. 仓库配置了签名密钥时产出正式签名包，可以覆盖升级；未配置时是 debug 签名包——同样能装，但换签名升级前要先卸载。

快速开始#

四步接管你的第一个 Agent。全程也可以用 Ctrl/⌘ K 命令面板完成——它是所有操作的最快入口。

第 1 步：添加主机

远程主机需要三样信息：

• 地址与用户名：与你平时 ssh user@host 用的相同。
• 认证方式三选一：ssh-agent（推荐，什么都不用填）、私钥文件（可带口令）、或密码。
• 跳板机（可选）：需要经过堡垒机的环境直接配置 jump host 链。

本机只需要起个名字——不需要 sshd、不需要任何凭据。Windows 用户会看到两个可选的本机： WSL 发行版与原生 Windows，按要跑的工作选择（Unix 工具链选 WSL，MSVC/WPF 选原生）。

第 2 步：创建项目与工作区

工作区就是主机上的一个工作目录（通常是代码仓库根目录）。两种添加方式：

• 表单：选主机、填路径。
• 文件浏览器（更快）：打开该主机的文件浏览，找到目录，直接「添加为项目」——名称、路径、主机都是现成的，不用抄一遍。

第 3 步：添加 Agent 并启动

一个 Agent = 一个名字 + 一条启动命令。命令就是你平时在终端里敲的那条，例如：

# 各家 CLI 的常见启动命令，按需替换
claude                    # Claude Code
codex                     # OpenAI Codex CLI
gemini                    # Gemini CLI
aider --model sonnet      # Aider
opencode                  # OpenCode

点击 Start，Agent 就跑在该主机的 tmux 会话里了。Agent 的 API Key 配置在主机侧 （它自己的配置文件或环境变量），AgentMux 不读取也不代理这些密钥。

第 4 步：附着终端，开始干活

点击 Agent 或按 Ctrl/⌘ K 搜索它的名字即可附着。你看到的是完整终端—— 彩色输出、鼠标、选中、搜索——可以随时介入打字、纠正 Agent 方向，再把控制权交回去，无需重启任务。 右侧面板同时提供 Start / Stop / Restart / Attach 按钮、进程状态与最近输出。

终端窗格墙#

终端区可以拆成最多 3×3 九个窗格，每个窗格持有独立的会话——可以在同一台主机，也可以横跨多台， 各自独立交互。要点：

• 添加窗格：Ctrl/⌘ \。有空闲标签页时立即分屏填入；否则弹出对话框，从主机、工作区目录、运行中的 Agent 与已打开标签中选择要附着的内容。
• 布局自适应：窗格按比例而非像素划分。窗口变窄时，读不了的窄列会被去掉，3×3 的墙自动折成更高的网格，而不是九条细缝。
• 拖动分隔缝调整每个窗格的占比。
• 临时全屏：双击窗格标签（或 Ctrl/⌘ ⇧ ↵）让它占满整个区域，再来一次还原——原来的分屏布局不受影响。
• 窗格是视图，不是会话：关闭窗格（Ctrl/⌘ ⇧ \）只是收起终端，标签页和它的 shell 保持连接。窗格数量在下次启动时自动恢复。

快捷键参考#

批量下发与回执#

Broadcast 面板可以把同一条指令发给任意选中的 Agent——跨项目、跨主机。与直接往每个终端里粘贴不同， 每个 Agent 会返回一张送达回执，明确告诉你指令是否真的到达。

• 按项目、按主机圈选目标，或手动逐个勾选。
• 逐 Agent 显示送达状态；失败的投递单独标出，可以单独重试。
• 典型用途：让全部 Agent 暂停当前工作、统一下发新的约束（“接下来所有提交信息用英文”）、批量询问进度。

主机运维#

安装面板：给新主机装环境

安装面板会先探测主机，只列出它真正能装的 Agent CLI 与运行时，并说明其余为何不可用 （比如缺少某个依赖）。选择要装的项后，安装过程在 tmux 内执行——即使连接中断，也不会留下装了一半的包树。 tmux 本身缺失时也可以从这里代装。

可一键安装的清单包括 Claude Code、Codex、Gemini CLI、Grok CLI、OpenCode、Aider、Cursor CLI 等 Agent CLI， 以及 Node、Python、tmux、Docker 与 Ollama 等运行时。Docker 提供六种安装方式（官方脚本优先，其次各发行版自带包， macOS 走 Homebrew 的 Docker Desktop），网络需要镜像时会自动重试；装完还会顺手启动守护进程、把当前用户加入 docker 组， 并明确提示该组要重新登录才生效。

主机遥测

每台主机的指标在单条命令内采集完成，包含：

• CPU（按模式与按核心）、内存、负载
• 磁盘用量与吞吐、网络流量、文件描述符
• NVIDIA GPU 利用率（有 GPU 的主机）

SFTP 文件浏览与编辑

基于同一条 SSH 连接提供文件浏览器和编辑器。写入是原子的，并带修改时间校验： 如果同目录下有 Agent 改过这个文件，保存会被拒绝而不是静默覆盖——先看它改了什么再决定。

远程桌面（内置 RDP / VNC 查看器）

有些工作是一块屏幕：坚持要弹窗的安装程序、GUI 测试、需要人盯着看的机器。右键主机选择打开桌面， AgentMux 会并发探测 3389（RDP）与 5900 / 5901（VNC）三个常见端口——刻意不做端口扫描。 对 SSH 主机，请求走的是这台主机已有的那条 SSH 连接，因此只监听环回地址的桌面无需对外开放任何端口， 也不需要第二套凭据。

• 查看器就在应用里：桌面画面直接显示为终端区的一个标签页，可以和终端窗格并排。它是真正的协议客户端而不是画面截图——VNC 走 noVNC，RDP 走 IronRDP 的 WebAssembly 构建，按需加载，从不开桌面的人不为它付出一个字节。画面尺寸自动跟随窗格大小。
• 因为查看器在应用里，这个能力在每种客户端上都可用：桌面 App、浏览器、平板、手机——不再依赖本机装了什么。
• 登录凭据在开会话时输入，经既有通道送达主机，哪儿都不存。
• Windows 拒绝登录时给出的是人话而不是 NT 状态码：账号锁定（以及多久自动解锁）、密码过期、账号被禁用、不在 Remote Desktop Users 组、登录时段限制、缺域名前缀等常见原因都会被翻译出来并附带解法。
• 桌面 App 上仍可选择「系统客户端」：把应答端口经 SSH 转发到本机环回地址，交给已有的查看器（Windows 的 mstsc、macOS 的「屏幕共享」、Linux 的 Remmina / FreeRDP）。最后一个客户端离开五分钟后通道自动关闭，释放持有 SSH 连接的租约；没装查看器时转发保持开启并把地址报给你。
• 某台主机提供的是哪种桌面会被记住——只记真正应答过的端点，拨错的端口不会被记下——第二次打开不再询问。这份记忆属于主机而非本机安装，所以它会随配置导出一起走。

屏幕专用主机

想看一台机器和想在一台机器上干活是两种不同的需求。添加主机时选「远程桌面」类型 就是前者：只填名称、地址和系统——系统决定协议（Windows 走 RDP，macOS / Linux 走 VNC），端口自动推出、可改。 没有任何凭据字段：桌面自己要的账号密码在开会话时才输，哪儿都不存。

• 它在树上就是一块屏幕：没有终端、不跑 Agent、不建工作区、不能当跳板机，也不占用 SSH 连接池——所有需要 shell 的地方都不会把它列为候选。
• 连接方式是直连它的桌面端口，就像任何一个普通远程桌面客户端；「测试连接」直接拨该端口并报告延迟。
• 升级为可干活的主机：它的详情面板会顺手探测 22 端口。SSH 已开时给出「添加为 SSH 主机」按钮——地址端口都已填好，新增一台完整主机，屏幕这一行原样保留；Windows 上 SSH 未开时，面板给出启用 OpenSSH Server 的整条 PowerShell 命令（附一键复制），在旁边已经打开的桌面窗格里粘贴执行，回来点刷新即可。
• 启用 OpenSSH 后按「远程 Windows」类型添加，Agent 就能原生运行——PowerShell、MSVC、WPF——由 AgentMux 的会话守护进程保活，关掉窗口活儿继续跑。从此这台机器既能看屏幕，又能干活。

主机硬件规格

指标面板除了「这台机器在干什么」，也回答「这台机器是什么」：CPU 型号、内存条规格、物理磁盘与显卡。 这些是静态信息，走一次性读取并按会话缓存，不占用三秒一次的指标轮询。

无头服务器#

AgentMux 的核心可以脱离窗口独立运行：一份不链接 GTK/WebKit 的完全静态无头构建， 在任何 Linux 服务器上跑起来就对外提供完整的 Web 应用——终端、Agent、批量下发、文件浏览、 远程桌面，与桌面版同源同功能，不是缩水视图。桌面 App、手机、平板、任何浏览器都可以连上它， 看到同一份主机配置和同一批正在跑的会话。

一行安装（推荐）

curl -fsSL https://raw.githubusercontent.com/tan-zhuo/AgentMux/main/scripts/install-server.sh | bash

脚本在一台 Linux 服务器（amd64 / arm64）上完成全部工作，全程以当前用户身份运行，不需要 root：

• 下载当前架构的服务器版并校验 .sha256，安装到 ~/.local/bin——先写新文件再原子改名，永远不会出现半个二进制。
• 注册 systemd 用户服务（~/.config/systemd/user/agentmux.service，失败自动重启），并开启 linger——SSH 断开、登出之后服务照常运行。没有 systemd 的机器自动退回 nohup + @reboot crontab。
• 默认开启 HTTPS（自签名证书），监听 :8642。
• 启动后先探测确认服务真的在应答，才报告安装成功；起不来时直接把服务日志的相关行打给你，并提示最常见的原因（端口被占，用 --addr 换一个）。
• 成功后打印连接要用的三样东西：地址、访问令牌、证书指纹。

常用选项（通过管道执行时写在 bash -s -- 之后）：

手动运行

# 服务器版（agentmux-server-linux-*）：跑起来就是服务，默认 :8642、明文 HTTP
./agentmux

# 带参数：监听所有网卡并开启自签 HTTPS
./agentmux --addr 0.0.0.0:8642 --tls

# 桌面版二进制进入同一模式
agentmux --serve --addr 0.0.0.0:8642 --tls

首次启动日志会打印访问令牌（48 位十六进制，同时保存在数据目录的 serve-token，权限 0600）， 开启 TLS 时还有一行证书 SHA-256 指纹——客户端配对时要核对的就是它。

加密与信任：自签证书 + 指纹钉住

自签证书没有 CA 背书，信任由每台设备自己决定：客户端首次连接会取回证书并展示其 SHA-256 指纹，你与服务器启动日志里的那一行核对一致后点「信任并连接」。此后该设备只认这一张证书—— 不看域名、不看有效期，指纹变了立即拒绝连接。换成正规 CA 证书后，钉住自动失效、走正常验证。 界面上所有该抄的值——令牌、地址、指纹——都带一键复制：它们是给剪贴板的，不是给眼睛抄的。

限制：服务器版目前只发布 Linux（amd64 / arm64）。macOS / Windows 想对外提供服务， 用桌面版的服务器模式，或自行 go build -tags headless。

核心切换与服务器模式#

每个 AgentMux 窗口背后都有一个「核心」——持有主机配置、SSH 连接、密钥与全部状态的那部分。 窗口默认看着本机的核心，但两者可以解耦：窗口可以改看别的机器上的核心；本机的核心也可以 开放给别的设备来看。这两个方向就是设置里相邻的两页。

把窗口指向远程核心（设置 → 连接模式）

1. 选「远程服务器」，填一台 serve 实例的地址，例如 https://192.168.1.10:8642。
2. 对方是自签 HTTPS 时会弹出证书指纹卡片：与服务器日志（或对方「服务器模式」页面）里的指纹核对一致后，点「指纹一致，信任并连接」。
3. 首次连接输入那台机器的访问令牌，窗口随即切换过去。

切换后这个窗口就是那台机器的一块屏幕：主机配置、SSH 密钥、连接、全部状态都在远程那端， 本机只记住地址与指纹。切回「本机核心」看到的又是本地那份数据——两边各自独立，互不同步。

• 推荐用法：家里的台式机或一台内网服务器跑核心（无头版或服务器模式），笔记本、手机、平板全部指向它——SSH 密钥与跳板机只需在那一台上配置一次，所有设备看到同一批主机、同一批正在跑的终端。
• 回得来：远端不可达时不会白屏——窗口显示一页错误说明，带「重试」与「切回本机核心」两个按钮。
• 安卓 App 里有同样的「设置 → 连接模式」：默认用内嵌在设备里的核心，也可以指向一台远程实例。

把这台电脑变成服务器（设置 → 服务器模式）

反过来，桌面 App 自己就能开放给其他设备连接——不用另装任何东西：

1. 设置 → 服务器模式，确认监听地址：默认 :8642 监听所有网卡；127.0.0.1:8642 只允许本机。
2. 「加密（HTTPS，自签名证书）」默认勾选，点「开启」。
3. 页面随即列出连接地址、访问令牌、证书指纹三样，各带一键复制——在手机 App 的「设置 → 连接模式」里填地址、输令牌、核对指纹即可。

窗口与网页是同一个核心的两副面孔：手机上看到的就是你桌面上那批主机与终端，操作实时互通。 开关状态会被记住，下次启动自动恢复。

平板与手机#

任何现代浏览器都能打开完整的应用——安卓平板、iPad、手机。 终端、Agent、工具箱、文件浏览、远程桌面全部可用，不是缩水的只读视图。

接入一台服务端

先按无头服务器一节起一个服务端（一行脚本装在 Linux 服务器上）， 或在桌面 App 里打开服务器模式。 两条路都会给你三样东西：地址、访问令牌、证书指纹。

在平板上打开

1. 浏览器访问 https://主机:8642（自签证书首次需要在浏览器的证书警告页选择继续访问；明文部署则是 http://）。
2. 输入一次令牌，之后由浏览器保存。
3. iPad：Safari「分享 → 添加到主屏幕」；安卓：Chrome「添加到主屏幕」。之后它就是一个独立 App，没有浏览器地址栏。

关闭浏览器不会停掉任何东西——和关掉桌面窗口一样，Agent 都活在远端的 tmux 里。

安卓原生 App

每个 Release 附带 agentmux-android.apk（Android 8.0+ · arm64）。它比上面那条路径更进一步： 内嵌了与服务器版同源的完整核心，由前台服务在设备本机拉起，WebView 连 127.0.0.1。 SSH 直接从手机或平板发起，配置与密钥存在设备本地——不需要任何一台常开的机器。

• 前台服务是刻意的：没有它，锁屏后安卓会冻结进程并掐断所有 SSH 连接。因此通知栏会有一条常驻通知。
• Agent 本身活在远端 tmux 里，应用被系统杀掉也不影响它们——重开应用即重连。
• 远程模式：在 App 的「设置 → 连接模式」里填一台 serve 实例的地址即可改连远程核心。对方是自签 HTTPS 时，App 会取回证书、展示指纹卡片，与服务器日志核对后点「指纹一致，信任并连接」——此后这台设备只认这张证书。
• 已知限制：连「自签 HTTPS + 指纹钉住」的服务端时，远程桌面查看器不可用（安卓 WebView 不把 WebSocket 的证书错误交给应用裁决）。终端等其余功能不受影响；换正规 CA 证书即可解除。

为拇指重做的布局

• 宽度不足 768px 时，左右两侧的面板变成覆盖式抽屉，一次只开一个，选中标签后自动收起。
• 状态栏的位置让给底部导航栏：集群树、命令面板、详情面板、设置，四个拇指高度的按钮，并尊重系统安全区。
• 对话框与命令面板不再坚持桌面的边距，在没有余量的屏幕上会自适应铺满。

编排器与 Ollama#

编排器是一个由本地模型驱动的运维助手：给它一个目标（例如「查明 agent-3 为什么停止推进」）， 它读取集群状态、检索既有上下文，一次一个工具调用地推进。默认关闭，需要你主动启用。

前置条件

1. 安装 Ollama 并保持运行。
2. 拉取一个对话模型和一个 embedding 模型，例如：

ollama pull qwen3          # 对话模型（示例，按机器配置选择）
ollama pull nomic-embed-text  # embedding 模型，用于语义检索

审批流程

• 任何会修改主机的操作都被挂起，等待你显式审批。审批卡片展示：工具名、完整参数、目标主机、模型给出的理由。
• 破坏性操作在所有主机上都要确认，与主机的信任级别无关。
• 工具是固定白名单，每个工具在声明时就绑定风险档；执行只能通过唯一的闸门——风险档 × 主机信任级别 × 触发来源共同决定放行与否。
• 远程主机的输出以「数据」标记进入模型上下文；形似指令的文本会在审批卡片和决策日志中触发警示（防提示注入）。
• 每次运行的每一步都被记录——包括被拒绝、被否决和无人应答的提议。

定时巡检

可以安排编排器定时巡视集群、报告停滞的 Agent。定时运行被无条件拒绝一切非只读工具， 该限制不可配置——巡检能发现问题，但无权动手，动手永远等你审批。

技能与记忆

• 技能：可复用的运维程序——适用条件、步骤、涉及工具与约束。条件再次出现时自动匹配。编排器提出的技能进入审核队列，未经批准不产生任何影响。
• 记忆：项目事实、你声明的偏好、Agent 活动都被索引，支持按原文或语义检索。embedding 本地生成，内容不出本机；匹配已知模式的凭据在入库前自动脱敏。

生命周期语义#

这几条语义想清楚了，就不会有「我是不是把任务弄丢了」的慌张时刻：

Agent 状态标记

在提问的 Agent、跑完等你看结果的 Agent、闲在提示符前的 Agent——过去在树上都只是一个「running」。 现在轮询会读每个 pane 并分类，在需要人介入的转变上立起一个持久标记， 直到有人真的去看了（打开终端、回答、或手动忽略）才落下。

• 标记出现在集群树的行上，并向上冒泡到折叠起来的工作区与项目——不展开也能看见哪里需要你。
• 终端标签页与右侧详情面板上同样有。

断线自动重连

终端失去连接不等于任务结束：远端的 tmux 会话还在跑，Agent 还在干活，断掉的只是管道。 所以管道会被重建——同一个 shell id、同一份滚动缓冲、同一个 pane，退避从 1 秒逐步拉到 15 秒， 约五分钟后放弃自动重试，此时原来的手动重连按钮仍在。

• 正常退出的会话不会被打扰：退出码是一个决定，不是一次故障。
• 两种 keepalive 各答一个问题——TCP keepalive 让中间设备不要忘记空闲连接；SSH keepalive 证明对端还在应答，且十秒没回就判定失败。
• 一次性命令终端不参与重连：重拨意味着把命令再跑一遍，因为 WiFi 闪断而重装一次包不是任何人想要的副作用。

更新与迁移#

自动检查与一键升级

应用在启动后不久、以及此后每六小时检查一次发布源。有新版本时，标题栏下方会出现一行横幅： 升级并重启、查看更新说明、或稍后。

• 升级会下载当前平台对应的资产并显示进度，校验随发布公布的 sha256，然后替换正在运行的可执行文件（macOS 换整个 bundle；Windows 上运行中的程序不能删除，改为改名让位），重启，并在下次启动时清理残留。
• 替换失败会回滚到原来正在运行的那个构建。
• 开发构建永远不会被覆盖——它通过 git 更新，设置里点检查时会直接这么告诉你。

把整套配置带到另一台电脑

设置里可以把全部配置写进一个文件：主机、文件夹、项目、工作区与 Agent 定义，需要的话还可以带上技能库与偏好设置， 然后在另一台电脑打开它。

• 加密方式：用你设的口令而不是本机主密钥——主密钥在这台电脑的钥匙串里，带不走，直接复制数据库到对面根本读不出来。Argon2id 把口令变成密钥，AES-256-GCM 封装内容；成本参数必须明文随行才能使用，因此它们是被认证而非隐藏的：把头部改成一个廉价参数会导致文件打不开，而不是变弱。
• SSH 密码与密钥口令：只有你要求时才随行，明文只存在于封装的那一瞬间，到达对面后立即用新机器自己的主密钥重新封存。
• 导入永不覆盖：同址的主机、同名的项目、同机同路径的目录，一律保持原样，文件里指向它的东西改为指向这边已有的那份。所以同一个文件导入两次不会多出任何东西，试一次导入也不会有代价。数不清的会明说——不在本机的密钥文件、没能随行的跳板机、这边已被占用的会话名。
• 两样东西刻意留在原地：终端布局与 Agent 运行时状态描述的是「这一份安装」而不是配置；编排器是否获准动手，则由每台机器各自决定——一个从别处来的文件不构成那个决定。

从源码构建#

需要 Go 1.25+ 与 Node 20+。前端先构建（会被嵌入二进制），再编译 Go：

git clone git@github.com:tan-zhuo/AgentMux.git
cd AgentMux
cd frontend && npm install && npm run build && cd ..
go build -o agentmux .
./agentmux

Linux 需要 WebKitGTK 头文件，并带 gtk3 构建标签：

sudo apt-get install -y build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev
go build -tags gtk3 -o agentmux .

Windows 上要产出双击运行的 GUI 程序（不带控制台窗口）：

go build -ldflags "-H windowsgui" -o agentmux.exe .

更多细节（测试、发版流程）见仓库内 docs/development.md。

故障排查#

macOS 提示「已损坏」或无法打开

这是未签名构建的正常拦截，不是文件损坏。按安装一节的表格处理， 或一条命令解决：xattr -dr com.apple.quarantine /Applications/AgentMux.app。

Linux 启动失败 / 报缺少库

几乎都是缺 WebKitGTK 运行时。Debian/Ubuntu：sudo apt install libwebkit2gtk-4.1-0； Fedora：sudo dnf install webkit2gtk4.1。

Windows 启动后没有任何窗口

GUI 构建的报错不进控制台。查看数据目录（%APPDATA%\AgentMux）下的 startup-error.log，里面是启动失败的具体原因。

连接主机时报 host key mismatch

主机指纹与首次连接时固定的不一致。先确认原因：主机重装过系统 / 换过 IP 对应的机器属正常， 删除该主机记录重新添加即可；如果什么都没变过，则要警惕中间人攻击，先从别的渠道核实主机指纹。

状态栏提示钥匙串不可用

加密主密钥正常存放在系统钥匙串（Keychain / Credential Manager / Secret Service）。 钥匙串不可用时（常见于精简的 Linux 桌面环境），AgentMux 退回到 0600 权限文件存储并在状态栏声明。 功能不受影响；想恢复钥匙串存储，Linux 上安装并启用 gnome-keyring 或其他 Secret Service 实现即可。

目标主机没有 tmux

打开该主机的安装面板，tmux 在可安装列表里——AgentMux 会在正确的包管理器下代装。

编排器 / 语义检索不可用

检查 Ollama 是否在运行（ollama list 能列出模型），且对话模型与 embedding 模型都已拉取。 没有 Ollama 时这两项功能保持禁用，其余功能不受影响。

我的数据存在哪里？

全部状态是应用数据目录下的一个 SQLite 文件（Windows 为 %APPDATA%\AgentMux）。 备份该目录即备份全部配置；删除它即彻底重置。凭据以 AES-256-GCM 加密存储，密钥在系统钥匙串中。

平板打不开 主机:8642

• 核对协议：安装脚本默认开启 TLS，要用 https:// 打开；手动裸跑未加 --tls 时才是 http://。自签证书首次访问需在浏览器证书警告页选择继续。
• 确认监听地址不是只绑 127.0.0.1——那样局域网访问不到（默认 :8642 监听所有网卡）。
• 检查服务器防火墙是否放行 8642（云主机还要看安全组）。
• 确认平板与服务端在同一网络，或已经连上同一条 VPN。

切到远程核心后一直是错误页

错误页本身就是设计的一部分：远端 serve 实例没起来、VPN 没连、地址写错时都会显示它， 并说明失败原因。点「重试」，或「切回本机核心」后检查那台服务器上 systemctl --user status agentmux 的输出。切换永远回得来，不会被困在远程模式里。

忘了 serve 模式的访问令牌

令牌保存在数据目录的 serve-token 文件里，首次启动时也打印在日志中。 想换一个：删掉该文件重启，或者启动时用环境变量 AGENTMUX_TOKEN 指定。

安卓 App 装不上或无法覆盖升级

先允许「安装未知来源应用」。如果提示签名冲突，说明装的是 debug 签名包（仓库未配置签名密钥时的产物）—— 先卸载旧版再安装新版即可，Agent 都活在远端 tmux 里，不会受影响。

获取帮助#

• 提交 GitHub Issue——附上平台、版本与 startup-error.log（如有）会大大加快定位。
• 编排器的设计细节（工具闸门、信任级别、记忆与技能层）见 编排器设计文档。
• 作者博客：tanzhuo.xyz