使用文档

AgentMux 是什么#

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

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

环境要求#

运行 AgentMux 的电脑

被管理的主机

• 远程主机：POSIX shell、tmux、一个 SSH 账号。缺 tmux 不要紧——AgentMux 的安装面板可以代装。暂不支持远程 Windows 主机。
• 本机（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

快速开始#

四步接管你的第一个 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 本身缺失时也可以从这里代装。

主机遥测

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

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

SFTP 文件浏览与编辑

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

编排器与 Ollama#

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

前置条件

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

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

审批流程

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

定时巡检

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

技能与记忆

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

生命周期语义#

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

从源码构建#

需要 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 加密存储，密钥在系统钥匙串中。

获取帮助#

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