cmux-settings

cmux-settings

cmux 從 ~/.config/cmux/cmux.json（JSONC 格式）讀取使用者設定。應用程式會安裝檔案監視器；儲存檔案後會立即套用變更，無需重新啟動。舊版的 ~/.config/cmux/settings.json 僅在 cmux.json 中缺少某個按鍵時作為備用讀取。

Schema：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 註解、原子寫入，並根據 schema 驗證按鍵。

# 從 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 必須符合 schema 列舉。綁定前請先查閱 references/shortcut-actions.md。
• 顏色值必須為 #RRGGBB。透明度為 0..1。
• 若使用者以應用程式層級的語言描述設定（例如「設定 > 通知 > Dock 徽章」），請先轉換為對應的 JSON 路徑；文件頁面 web/app/[locale]/docs/configuration/page.tsx 與 schema 完全對應。