cmux 使用速查

概述

cmux 是一个基于 Ghostty 的 macOS 原生终端，用来组织多个 AI 编程代理、终端、浏览器预览和工作区。它不是 tmux 的配置文件替代品，而是把窗口、工作区、分屏、标签页、命令面板和通知做成一个更适合代理并行工作的终端环境。

日常使用时，最需要先记住三件事：⌘ + ⇧ + P 打开命令面板，⌘ + N 新建工作区，⌘ + T 新建终端标签页。其余快捷键可以按类别查表。

安装启动

官方推荐直接下载 DMG，也可以用 Homebrew 安装：

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

后续更新：

brew upgrade --cask cmux

cmux 要求 macOS 14.0 或更高版本。第一次启动后，会看到左侧工作区栏和一个已经打开的终端工作区。

如需在 cmux 外部使用命令行工具，可以建立软链接：

sudo ln -sf "/Applications/cmux.app/Contents/Resources/bin/cmux" /usr/local/bin/cmux

之后可以在普通终端里执行：

cmux list-workspaces
cmux notify --title "Build Complete" --body "Your build finished"

界面层级

cmux 的层级可以按下面理解：

Window
└── Workspace
    └── Pane
        └── Surface
            └── Panel

• Window：macOS 窗口。
• Workspace：左侧栏里的工作区，每个工作区有自己的分屏和标签页。
• Pane：分屏区域。
• Surface：某个分屏里的标签页，可以是终端，也可以是浏览器。
• Panel：真正显示内容的终端或浏览器面板。

很多快捷键都围绕 Workspace、Pane 和 Surface 展开。先把这三个词认清，查快捷键时会省很多脑内翻译。

按键记法

下文使用 macOS 记法：

• ⌘：Command。
• ⌃：Control。
• ⌥：Option。
• ⇧：Shift。
• ↩：Enter。
• ←、→、↑、↓：方向键。

cmux 自己接管的快捷键可以在设置里改，也可以写入 ~/.config/cmux/cmux.json。终端里的 shell 快捷键，例如 Ctrl + C、Ctrl + D、Ctrl + A，仍然由终端进程处理。

先记快捷键

这一组覆盖了大多数高频操作：

快捷键	作用	说明
⌘ + ⇧ + P	命令面板	搜索内置命令、自定义命令和动作
⌘ + ,	设置	打开设置界面
⌘ + ⇧ + ,	重新加载配置	修改 cmux.json 后使用
⌘ + B	显示 / 隐藏侧边栏	小屏幕下很常用
⌘ + N	新建工作区	在左侧栏创建 workspace
⌘ + O	打开文件夹	把目录打开成工作区
⌘ + P	切换工作区	打开 workspace switcher
⌘ + T	新建终端标签页	在当前分屏里创建 surface
⌘ + D	向右分屏	新建右侧 pane
⌘ + ⇧ + D	向下分屏	新建下方 pane
⌥ + ⌘ + 方向键	切换分屏焦点	在相邻 pane 间移动
⌘ + F	查找	在当前内容里搜索
⌘ + I	通知面板	查看通知列表
⌘ + Q	退出	退出 cmux

忘记具体入口时，优先按 ⌘ + ⇧ + P 搜索。自定义命令、工作区模板、代理启动动作都会出现在命令面板里。

应用窗口

快捷键	作用
⌘ + ,	打开设置
⌘ + ⇧ + ,	重新加载配置
⌃ + ⌥ + ⌘ + .	全局显示 / 隐藏所有 cmux 窗口
⌘ + ⇧ + P	打开命令面板
⌃ + N	命令面板下一项
⌃ + P	命令面板上一项
⌘ + ⇧ + N	新建窗口
⌃ + ⌘ + W	关闭窗口
⌃ + ⌘ + F	切换全屏
⌥ + ⌘ + F	发送反馈
⌘ + ⇧ + O	重新打开上一次会话
⌘ + Q	退出 cmux

⌘ + ⇧ + , 很适合放在配置修改流程里：编辑 cmux.json，保存，然后重新加载，不必退出应用。

工作区

快捷键	作用	说明
⌘ + B	显示 / 隐藏侧边栏	左侧 workspace 栏
⌘ + N	新建工作区	默认插入位置可配置
⌘ + O	打开文件夹	从目录创建工作区
⌘ + P	切换工作区	打开工作区切换器
⌃ + ⌘ + ]	下一个工作区	左侧栏顺序向后
⌃ + ⌘ + [	上一个工作区	左侧栏顺序向前
⌘ + 1…9	选择第 1 到第 9 个工作区	快速跳转
⌘ + ⇧ + R	重命名工作区	给代理任务起可识别的名字
⌥ + ⌘ + E	编辑工作区描述	记录任务目标或上下文
⌘ + ⇧ + E	切换右侧栏焦点	右侧栏聚焦后可继续导航
⌥ + ⌘ + B	显示 / 隐藏右侧栏	控制文件、查找、会话等侧栏
J / K	右侧栏上下移动	右侧栏聚焦时生效
H / L	折叠 / 展开文件夹	文件树里生效
/	搜索右侧栏	文件树或列表里快速过滤
⌘ + ⇧ + W	关闭工作区	关闭前确认终端进程是否还要保留

工作区名建议写成具体任务，例如“登录页改版”“接口联调”“Claude 修复构建”。代理、日志和预览多起来以后，具体名称比颜色更可靠。

标签页

Surface 是某个分屏里的标签页，常见内容是终端或浏览器。

快捷键	作用	说明
⌘ + T	新建标签页	默认创建终端 surface
⌘ + ⇧ + ]	下一个标签页	当前 pane 内切换
⌘ + ⇧ + [	上一个标签页	当前 pane 内切换
⌃ + 1…9	选择第 1 到第 9 个标签页	当前 pane 内跳转
⌘ + R	重命名标签页	例如 Codex、Claude、Server
⌘ + W	关闭标签页	关闭当前 surface
⌥ + ⌘ + T	关闭当前 pane 内其他标签页	清理临时终端
⌘ + ⇧ + T	重新打开关闭的浏览器面板	用于浏览器 surface
⌘ + ⇧ + M	切换终端复制模式	适合复制长输出
⌘ + S	保存文件预览	文本预览聚焦时生效

一个常用模式是：同一个工作区里，Server 跑开发服务，Codex 跑代理，Shell 做临时命令，Preview 打开浏览器预览。

分屏

快捷键	作用
⌥ + ⌘ + ←	聚焦左侧分屏
⌥ + ⌘ + →	聚焦右侧分屏
⌥ + ⌘ + ↑	聚焦上方分屏
⌥ + ⌘ + ↓	聚焦下方分屏
⌘ + D	向右分屏
⌘ + ⇧ + D	向下分屏
⌥ + ⌘ + D	向右分出浏览器
⌥ + ⌘ + ⇧ + D	向下分出浏览器
⌘ + ⇧ + ↩	放大 / 还原当前分屏
⌃ + ⌘ + =	均分分屏尺寸

分屏不用开太多。两个代理、一个服务日志、一个浏览器预览已经够忙；再多就要靠工作区拆分了。

浏览器

cmux 可以在内置浏览器里打开本地服务、PR 链接或文档页面。

快捷键	作用
⌘ + ⇧ + L	打开浏览器
⌘ + L	聚焦地址栏
⌘ + [	后退
⌘ + ]	前进
⌘ + R	刷新页面
⌘ + =	放大
⌘ + -	缩小
⌘ + 0	恢复实际大小
⌥ + ⌘ + I	打开开发者工具
⌥ + ⌘ + C	打开 JavaScript 控制台
⌘ + ⇧ + G	切换 React Grab

前端项目可以把浏览器和开发服务放进同一个工作区布局，减少在浏览器、终端和编辑器之间来回找窗口。

查找通知

快捷键	作用
⌘ + F	查找
⌘ + ⇧ + F	在目录中查找
⌘ + G	下一个匹配项
⌥ + ⌘ + G	上一个匹配项
⌥ + ⌘ + ⇧ + F	隐藏查找栏
⌘ + E	用选中内容查找
⌘ + I	显示通知
⌘ + ⇧ + U	跳到最新未读通知
⌘ + ⇧ + H	闪烁当前面板

通知适合代理等待输入、构建完成、长命令结束这类事件。不要把所有小状态都变成通知，否则很快会训练自己忽略红点。

终端按键

下面这些不是 cmux 独有快捷键，而是终端和 shell 里的常用按键。焦点在终端输入区时，它们通常会直接发给当前进程。

快捷键	作用
Ctrl + C	中断当前命令
Ctrl + D	结束输入或退出 shell
Ctrl + L	清屏
Ctrl + A	跳到行首
Ctrl + E	跳到行尾
Ctrl + U	删除到行首
Ctrl + K	删除到行尾
Ctrl + R	搜索 shell 历史
Cmd + C	有选区时复制
Cmd + V	粘贴

快捷键没反应时先看焦点：焦点在终端程序里，按键可能被 vim、tmux、代理 CLI 或 shell 接走；焦点在 cmux 的列表、标签栏、命令面板里，才会触发 cmux 动作。

配置文件

cmux 的配置分两类：终端渲染配置和应用配置。

终端渲染读取 Ghostty 配置文件，按顺序查找：

1. ~/.config/ghostty/config
2. ~/Library/Application Support/com.mitchellh.ghostty/config

应用配置、快捷键、动作、自定义命令和工作区布局写在 cmux.json：

1. ~/.config/cmux/cmux.json：全局配置。
2. .cmux/cmux.json：项目内配置，适合提交到仓库。
3. ./cmux.json：兼容旧仓库的本地配置。

修改后用 ⌘ + ⇧ + , 或命令行重新加载：

cmux reload-config

cmux.json 支持注释和尾随逗号。建议保留 $schema，编辑器可以据此做字段补全和校验。

终端外观

字体、字号、主题、滚动缓冲区等终端显示项写在 ~/.config/ghostty/config：

font-family = SF Mono
font-size = 13
theme = One Dark
scrollback-limit = 50000000
split-divider-color = #3e4451
working-directory = ~/code

从 Ghostty 迁移过来时，这部分配置可以直接沿用。应用层的侧边栏、通知、快捷键不要写到这里，它们属于 cmux.json。

应用偏好

下面是一份全局 ~/.config/cmux/cmux.json 示例：

{
  "$schema": "https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json",
  "schemaVersion": 1,
  "app": {
    "appearance": "dark",
    "newWorkspacePlacement": "afterCurrent",
    "warnBeforeQuit": true
  },
  "terminal": {
    "showScrollBar": true,
    "autoResumeAgentSessions": true
  },
  "notifications": {
    "dockBadge": true,
    "showInMenuBar": true,
    "sound": "default"
  },
  "sidebar": {
    "branchLayout": "inline",
    "showPorts": true,
    "showLog": true,
    "showProgress": true
  }
}

常用字段可以按下面理解：

• app.appearance：应用外观，可用 system、light、dark。
• app.newWorkspacePlacement：新工作区插入位置，可用 top、afterCurrent、end。
• app.warnBeforeQuit：退出前是否确认。
• terminal.showScrollBar：终端有滚动内容时是否显示滚动条。
• terminal.autoResumeAgentSessions：重新打开应用后是否自动运行代理恢复命令。
• notifications.sound：通知声音，设成 none 可以静音。
• sidebar.branchLayout：分支信息显示方式，可用 vertical 或 inline。

快捷键配置

快捷键可以在设置界面里改，也可以写入 shortcuts.bindings。单步快捷键用字符串，两段式快捷键用数组。

{
  "$schema": "https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json",
  "schemaVersion": 1,
  "shortcuts": {
    "showModifierHoldHints": true,
    "bindings": {
      "newSurface": ["ctrl+b", "c"],
      "showNotifications": ["ctrl+b", "i"],
      "toggleSidebar": "cmd+b",
      "splitRight": "",
      "commandPalettePrevious": null
    }
  }
}

几个细节要注意：

• "newSurface": ["ctrl+b", "c"] 表示先按 Ctrl + B，再按 C，接近 tmux 前缀键习惯。
• "splitRight": "" 表示取消绑定；null、"none"、"clear"、"unbound"、"disabled" 也可用于解绑。
• 快捷键项名对应 cmux 动作，例如 toggleSidebar、newSurface、splitRight。
• 改完后按 ⌘ + ⇧ + , 重新加载配置。

简单命令

项目内命令建议写到 .cmux/cmux.json。简单命令会在当前聚焦终端的工作目录里执行，并显示在命令面板中。

{
  "$schema": "https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json",
  "schemaVersion": 1,
  "commands": [
    {
      "name": "安装依赖",
      "keywords": ["install", "deps"],
      "command": "cd \"$(git rev-parse --show-toplevel)\" && pnpm install",
      "confirm": true
    },
    {
      "name": "构建检查",
      "keywords": ["build", "check"],
      "command": "cd \"$(git rev-parse --show-toplevel)\" && pnpm build",
      "confirm": true
    },
    {
      "name": "查看 Git 状态",
      "keywords": ["git", "status"],
      "command": "git status --short"
    }
  ]
}

command 默认跟着当前终端目录走。项目命令如果依赖仓库根目录，建议像示例一样先 cd "$(git rev-parse --show-toplevel)"，避免代理或临时 shell 切到子目录后跑错位置。

工作区命令

工作区命令可以一次创建分屏、终端标签页和浏览器预览。适合把“开发服务 + 浏览器预览 + 临时 shell”固化下来。

{
  "$schema": "https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json",
  "schemaVersion": 1,
  "commands": [
    {
      "name": "Web 开发环境",
      "keywords": ["dev", "web", "preview"],
      "workspace": {
        "name": "Web Dev",
        "cwd": ".",
        "color": "#3b82f6",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Dev Server",
                    "command": "pnpm dev",
                    "focus": true
                  }
                ]
              }
            },
            {
              "direction": "vertical",
              "split": 0.6,
              "children": [
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "browser",
                        "name": "Preview",
                        "url": "http://localhost:8000"
                      }
                    ]
                  }
                },
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "terminal",
                        "name": "Shell",
                        "env": {
                          "NODE_ENV": "development"
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

几个字段最常用：

• workspace.name：左侧栏显示的工作区名称。
• workspace.cwd：工作区根目录。
• workspace.color：工作区颜色。
• layout.direction：分屏方向，horizontal 或 vertical。
• layout.split：分割比例，范围通常是 0.1 到 0.9。
• surface.type：terminal 或 browser。
• surface.command：终端创建后自动执行的命令。
• surface.cwd：当前 surface 的工作目录。
• surface.env：当前 surface 的环境变量。
• surface.focus：创建后是否聚焦。

如果同名工作区已存在，可以配置重启行为：new 创建新的，ignore 切到已有的，recreate 直接重建，confirm 先询问再重建。

代理动作

actions 可以把常用代理做成命令面板入口、标签栏按钮或独立快捷键。官方文档标注动作注册表属于 nightly 功能；稳定版不可用时，优先使用上一节的 commands。

{
  "$schema": "https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json",
  "schemaVersion": 1,
  "actions": {
    "codex": {
      "type": "command",
      "title": "Codex",
      "subtitle": "Open Codex in a new terminal tab",
      "command": "codex",
      "target": "newTabInCurrentPane",
      "shortcut": "cmd+shift+x",
      "icon": { "type": "symbol", "name": "terminal" }
    },
    "claude": {
      "type": "command",
      "title": "Claude Code",
      "command": "claude",
      "target": "newTabInCurrentPane",
      "shortcut": "cmd+shift+c",
      "icon": { "type": "symbol", "name": "sparkles" }
    }
  },
  "ui": {
    "surfaceTabBar": {
      "buttons": [
        "cmux.newTerminal",
        "cmux.newBrowser",
        "cmux.splitRight",
        "cmux.splitDown",
        "codex",
        "claude"
      ]
    }
  }
}

target 常用两个值：

• currentTerminal：在当前终端里执行。
• newTabInCurrentPane：在当前分屏中新建标签页执行。

如果代理需要额外参数，把参数直接写进 command。项目共享配置里不要默认加入危险跳过权限的参数；这类参数最好留在个人全局配置里。

配置取舍

日常使用建议按下面顺序配置：

1. 在 Ghostty 配置里调好字体、字号、主题和滚动缓冲区。
2. 在全局 cmux.json 里配置快捷键、通知、侧边栏和个人代理动作。
3. 在项目 .cmux/cmux.json 里配置团队共享命令和工作区布局。
4. 把删除数据、发布上线、重置数据库这类危险命令留在手动流程里，不放进通用命令面板。

项目配置提交到仓库前，检查是否包含密钥、令牌、生产数据库地址和个人路径。命令面板很方便，但误触也很方便。

参考

• cmux Getting Started
• cmux Concepts
• cmux Keyboard Shortcuts
• cmux Configuration
• cmux Custom Commands
• cmux 配置 Schema