cmux-settings

cmux-settings

cmux 从 ~/.config/cmux/cmux.json（JSONC 格式）读取用户设置。应用会安装文件监视器；保存文件后更改立即生效，无需重启。旧的 ~/.config/cmux/settings.json 仅作为 cmux.json 中不存在的键的回退读取。

模式文件：https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json。权威路径列表位于 cmux 仓库的 Sources/CmuxSettingsJSONPathSupport.swift 中，安装的技能包含一份生成的副本在 references/all-keys.md。顶级部分包括 app、terminal、notifications、sidebar、sidebarAppearance、workspaceColors、automation、browser 和 shortcuts。非设置部分（actions、ui、commands、vault、rightSidebar）共存于同一文件中。

辅助脚本

每次读写都使用捆绑的辅助脚本。它会去除 JSONC 注释、原子写入并根据模式验证键。

# 从 cmux 仓库
skills/cmux-settings/scripts/cmux-settings <子命令>

# 从已安装的 Codex 技能
~/.codex/skills/cmux-settings/scripts/cmux-settings <子命令>

为简洁起见，本文档其余部分假设脚本已在 $PATH 中作为 cmux-settings。要在会话中从仓库实现这一点：export PATH="$PWD/skills/cmux-settings/scripts:$PATH"。

子命令：

命令	功能
cmux-settings path	打印配置路径。
cmux-settings dump	打印原始文件（保留注释）。
cmux-settings dump --no-comments	打印解析后的 JSON。
cmux-settings get <a.b.c>	打印点号分隔的 JSON 路径处的值。
cmux-settings set <a.b.c> <value>	设置值。<value> 被解析为 JSON（true、42、"text"、[…]、{…}）；不带引号的纯字符串作为字符串存储。
cmux-settings unset <a.b.c>	删除键，恢复为应用内默认值。
cmux-settings list-supported	列出应用识别的所有设置 JSON 路径。
cmux-settings validate	解析文件并标记任何未知的设置键。
cmux-settings open	在 $EDITOR、VS Code、Cursor 或 TextEdit 中打开 cmux.json。

--file <path> 覆盖目标文件（当用户使用旧文件时，可用于 --file ~/.config/cmux/settings.json）。

工作流程

1. 确认更改。如果用户用普通英语命名了设置（例如“让侧边栏色调匹配终端背景”），先查找它。

   cmux-settings list-supported | rg -i 'sidebar.*terminal|terminal.*sidebar'
   

2. 设置值。JSON 字面量（true、false、数字、数组、对象）必须是有效的 JSON。普通单词作为字符串存储。

   cmux-settings set sidebarAppearance.matchTerminalBackground true
   cmux-settings set app.appearance dark
   cmux-settings set shortcuts.bindings.toggleSidebar cmd+b
   cmux-settings set shortcuts.bindings.newTab '["ctrl+b","c"]'
   cmux-settings set browser.hostsToOpenInEmbeddedBrowser '["localhost","*.internal.example"]'
   

3. 通过回读和验证来确认。

   cmux-settings get sidebarAppearance.matchTerminalBackground
   cmux-settings validate
   

4. 告知用户设置已自动重新加载。无需重启应用。如果他们想恢复，运行 cmux-settings unset <key>。

快速参考

• 外观：app.appearance = "system" | "light" | "dark"、app.appIcon、app.menuBarOnly、app.minimalMode。
• 侧边栏色调：sidebarAppearance.matchTerminalBackground、sidebarAppearance.tintColor、sidebarAppearance.tintOpacity（0..1）。
• 侧边栏详情：sidebar.hideAllDetails、sidebar.showBranchDirectory、sidebar.showPullRequests、sidebar.showPorts、sidebar.showLog。
• 通知：notifications.dockBadge、notifications.sound（枚举包括 "none"、"custom_file"）、notifications.customSoundFilePath、notifications.hooks（数组）。
• 浏览器：browser.defaultSearchEngine、browser.theme、browser.openTerminalLinksInCmuxBrowser、browser.hostsToOpenInEmbeddedBrowser。
• 自动化：automation.socketControlMode（off | cmuxOnly | automation | password | allowAll）、automation.portBase、automation.portRange。
• 快捷键：shortcuts.bindings.<actionId> = "cmd+b"、["ctrl+b","c"]、null 或 "" 以取消绑定。参见 references/shortcut-actions.md。

有关设置的完整列表、默认值和描述，请运行 cmux-settings list-supported 或阅读 references/all-keys.md。

规则

• 仅编辑 cmux.json。除非用户明确要求，否则不要编辑 settings.json；它是旧版文件，仅在 cmux.json 中缺少键时读取。
• 切勿告诉用户重启 cmux 以应用更改。文件监视器会在保存时重新加载。
• 批量编辑后始终验证：cmux-settings validate。未知键意味着用户粘贴了应用不使用的键。
• 不要盲目覆盖顶级部分（actions、ui、commands、vault、rightSidebar）。它们位于同一文件中，包含用户手动调整的非设置配置。
• 快捷键操作 ID 必须匹配模式枚举。在绑定前，在 references/shortcut-actions.md 中查找它们。
• 颜色值必须为 #RRGGBB。透明度为 0..1。
• 对于用户以应用级语言表达的设置（例如“设置 > 通知 > Dock 徽章”），首先转换为匹配的 JSON 路径；文档页面 web/app/[locale]/docs/configuration/page.tsx 与模式一一对应。