📟 cmux 详细部署教程

cmux 是一款基于 Ghostty 构建的 macOS 终端增强工具，专为同时运行多个 AI 编码代理（如 Claude Code、Codex）的开发者设计。它提供了垂直标签页、通知系统、内置浏览器和强大的可编程接口，让您能高效地组织和管理多个终端会话。本教程将指导您完成安装、配置和基础使用。

📋 部署前准备

  • 操作系统：macOS（目前仅支持 macOS，原生 Swift + AppKit 构建）。
  • （可选）Ghostty 配置：cmux 会读取您现有的 ~/.config/ghostty/config 文件来应用主题、字体和颜色，因此如果您已有 Ghostty 配置，可以无缝迁移。
  • （可选）AI 编码代理：如果您计划使用 Claude Code、Codex 等工具，请确保它们已在您的 PATH 中。

📦 第一步：安装 cmux

cmux 提供了两种推荐的安装方式。

方式一：使用 DMG 安装包（推荐）

  1. 从项目的 GitHub Releases 页面 下载最新的 .dmg 文件。
  2. 打开 .dmg 文件，将 cmux.app 拖拽到 Applications 文件夹中。
  3. 首次启动时，macOS 可能会提示无法验证开发者，请在“系统设置 → 隐私与安全性”中点击“仍要打开”或右键点击应用选择“打开”并确认。
  4. cmux 内置了 Sparkle 自动更新框架，未来只需首次下载即可。

方式二：使用 Homebrew 安装

如果您习惯使用 Homebrew，也可以使用以下命令安装：

1
2
brew tap manaflow-ai/cmux
brew install --cask cmux

更新到最新版本：

1
brew upgrade --cask cmux

⚙️ 第二步：首次启动与基础配置

启动 cmux 后，您会看到一个类似 Ghostty 的终端界面，但左侧多了一个垂直侧边栏。

  1. 创建新工作区：按 ⌘ N 创建一个新的工作区 (Workspace)。每个工作区可以包含多个分屏 (Splits) 和标签页 (Tabs)。
  2. 打开终端分屏：按 ⌘ D 在当前工作区中向右分屏，按 ⌘ ⇧ D 向下分屏。您可以在分屏中分别运行不同的 AI 代理或命令。
  3. 切换分屏/工作区：使用 ⌘ 1-8 切换到对应编号的工作区，使用 ⌃ Tab / ⌘ ⇧ [ / ⌘ ⇧ ] 在分屏间切换。

应用 Ghostty 主题

cmux 会自动读取您 ~/.config/ghostty/config 中的配置。如果您没有这个文件，可以创建一个并填入主题设置，例如：

1
2
3
4
# ~/.config/ghostty/config
theme = "dark"            # 或您喜欢的主题名称
font-family = "JetBrains Mono"
font-size = 14

保存后，在 cmux 中按 ⌘ ⇧ , 重新加载配置即可生效。

🔔 第三步：核心功能：通知系统与 AI 代理集成

这是 cmux 最强大的功能之一，让您能一目了然地知道哪个代理需要您的关注。

1. 自动通知（终端转义序列）

当在 cmux 中运行的进程（如 AI 代理）输出特定的终端转义序列（OSC 9、99、777）时，cmux 会：

  • 在对应的终端分屏外圈显示蓝色光晕。
  • 在左侧边栏的标签页上点亮并显示最新的通知文本。
  • 在 macOS 桌面弹出系统通知。

2. 手动触发通知（CLI）

您也可以通过 cmux 的命令行工具手动触发通知，方便集成到脚本中：

1
cmux notify "消息标题" --body "这里是通知内容"

3. 为 AI 代理安装钩子 (Hooks)

为了让 Claude Code、Codex 等代理在需要输入时自动发送通知，您需要安装 cmux 提供的钩子脚本。

1
2
3
4
5
6
# 安装所有支持的代理钩子（代理需已在 PATH 中）
cmux hooks setup

# 或为特定代理安装
cmux hooks setup claude-code
cmux hooks setup codex

安装后，当代理执行任务并请求用户输入时，cmux 会自动通过通知系统提醒您。

4. 查看通知面板

按 ⌘ I 打开通知面板，您可以看到所有待处理的通知，并按 ⌘ ⇧ U 快速跳转到最新的一条未读通知所在的分屏。

🌐 第四步：内置浏览器与自动化

cmux 内置了一个可与终端并排显示的浏览器分屏，并且可以通过 API 进行脚本化控制。

  1. 打开浏览器分屏：按 ⌘ ⇧ L，在当前工作区右侧打开一个浏览器分屏。
  2. 与终端共存：您可以让 AI 代理在终端中运行开发服务器，同时在浏览器分屏中查看效果。
  3. 脚本化控制：cmux 提供了 CLI 和 Socket API，允许程序化地控制浏览器。例如，让代理执行以下操作：
    • 获取 DOM 快照：cmux browser snapshot
    • 点击元素：cmux browser click "#submit-btn"
    • 填写表单：cmux browser fill "input[name='query']" "search text"
    • 执行 JavaScript：cmux browser evaluate "document.title"
      这让 AI 代理能够自主验证自己的前端修改，而无需离开 cmux 环境。

🛠️ 第五步：高级功能

1. 会话恢复 (Session Restore)

cmux 会自动保存您的工作区布局、分屏、工作目录、终端回滚内容以及浏览器的 URL 和历史记录。

  • 当您退出并重新打开 cmux 时，所有状态都会被恢复。
  • AI 代理会话（如 Claude Code）也可以通过钩子恢复，按 ⌘ ⇧ O 或选择 File → Reopen Previous Session 手动恢复。

2. 自定义命令 (Skills)

cmux 支持可重复使用的技能 (Skills)。您可以通过 cmux.json 文件定义项目特定的命令，这些命令会出现在 cmux 的命令面板中。您可以浏览官方 cmux-skills 仓库 获取社区分享的技能。

3. SSH 远程工作区

您可以创建一个 SSH 会话作为新的工作区：

1
cmux ssh user@remote-host

cmux 会为远程机器创建一个独立的工作区，并且内置的浏览器分屏会通过远程网络路由，使 localhost 正常访问远程服务。

4. 可编程性 (CLI & Socket API)

cmux 的核心设计原则是可编程。除了 CLI 命令，它还提供了一个 Unix Socket API，允许您编写脚本或让代理程序化地控制整个应用，例如：

  • 创建新工作区：cmux workspace new "我的项目"
  • 拆分窗格：cmux split --direction right
  • 发送按键到终端：cmux send-keys "ls -la" Enter
    您可以在 官方文档 中找到完整的 API 参考。

🔧 常见问题与排障

  • macOS 提示“无法打开，因为无法验证开发者”？
    在系统设置中允许或右键点击应用图标，选择“打开”即可。或者使用命令行移除隔离属性：xattr -d com.apple.quarantine /Applications/cmux.app。
  • 代理不发送通知？
    确保已运行 cmux hooks setup 为您的代理安装了钩子，并且代理的二进制文件在 PATH 中。在代理的配置文件（如 Claude Code 的 ~/.claude-code/config.toml）中检查是否启用了钩子。
  • 终端字体/主题不生效？
    cmux 读取 ~/.config/ghostty/config，如果文件不存在或配置有误，将使用默认设置。修改后按 ⌘ ⇧ , 重新加载配置。
  • 如何查看所有键盘快捷键？
    在 cmux 中打开 设置 (Settings, ⌘ ,)，在键盘快捷键 (Keyboard Shortcuts) 部分可以查看和修改所有快捷键绑定。

通过以上步骤，您已经成功部署并掌握了 cmux 的基本用法。它是一个强大的“终端 + 浏览器 + 通知中心 + 自动化平台”的组合体，尤其适合需要同时与多个 AI 代理协作的深度用户。如需了解更多高级用法和配置选项，请务必查阅 官方文档 或在项目 GitHub 仓库中参与社区讨论。