# cmux 0.65.1 Ghostty 配置错误：One Dark 主题找不到的原因与解决方法

> 作者：zning（https://ning.ae） · 发布：2026/10/15 15:10 下午 (UTC+8) · 原文：https://zning.me/17920482007769.html

## 一、问题背景

最近在 macOS 上使用 [cmux](https://github.com/manaflow-ai/cmux) 时，遇到了一个 Ghostty 主题加载错误。

cmux 是一款基于 Ghostty 终端渲染引擎构建的 macOS 终端应用，支持多工作区、分屏、垂直标签页和通知面板，非常适合同时运行多个 CLI 工具及 AI Coding Agent。

本次使用的版本信息如下：

| 项目 | 版本 |
|---|---|
| 应用 | cmux |
| Version | 0.65.1 |
| Build | 110 |
| Commit | `8a853dcc9` |
| 操作系统 | macOS |
| 终端引擎 | libghostty |

![cmux 0.65.1 关于窗口](media/17920482007769/cmux-about.png)

该版本于 2026 年 10 月 12 日发布。

官方发布记录：[cmux v0.65.1](https://github.com/manaflow-ai/cmux/releases/tag/v0.65.1)。

启动 cmux 后，应用弹出了以下警告：

```text
Ghostty 配置错误

theme "One Dark" not found,
tried path "/Users/zning/.config/ghostty/themes/One Dark"

theme "One Dark" not found,
tried path "/Applications/cmux.app/Contents/Resources/ghostty/themes/One Dark"
```

![Ghostty 配置错误弹窗](media/17920482007769/ghostty-config-error.png)

提示还表示，修正配置并保存后，cmux 会自动重新加载。

虽然终端仍然可以使用，但每次出现配置错误提示显然不太理想。

最初怀疑是升级到 cmux 0.65.1 后，Ghostty 的主题资源发生了变化，或者新版本存在主题打包问题。

经过排查，问题在检查主题名称和配置文件的阶段就得到了解决，无需重新安装 cmux。

## 二、理解 cmux 与 Ghostty 的配置关系

排查之前，需要先理解 cmux 的终端渲染架构。

cmux 使用 **libghostty** 作为终端渲染引擎，因此它可以使用 Ghostty 的大部分终端配置，包括：

- 终端主题和配色方案
- 字体、字号和字形设置
- 光标样式
- 背景透明度和模糊效果
- 终端内边距和自定义 Shader

不过，cmux 也拥有自己的应用配置体系。

根据 [cmux 官方配置文档](https://github.com/manaflow-ai/cmux/blob/v0.65.1/docs/customizing-appearance.md)，主要涉及以下路径：

| 配置路径 | 用途 |
|---|---|
| `~/.config/ghostty/config` | Ghostty 共享配置 |
| `~/.config/ghostty/config.ghostty` | Ghostty 共享配置 |
| `~/Library/Application Support/com.mitchellh.ghostty/config.ghostty` | Ghostty macOS 配置 |
| `~/Library/Application Support/com.cmuxterm.app/config.ghostty` | cmux 专属 Ghostty 配置 |
| `~/.config/cmux/cmux.json` | cmux 应用界面、工作区及行为配置 |

其中有一个重要机制：

**cmux 会在加载 Ghostty 共享配置后，再加载自己的 `config.ghostty`，因此后者的同名配置具有更高优先级。**

例如：

```ini
# ~/.config/ghostty/config
theme = Catppuccin Mocha
```

如果同时存在：

```ini
# ~/Library/Application Support/com.cmuxterm.app/config.ghostty
theme = Atom One Dark
```

那么最终生效的主题配置会以 cmux 专属配置为准。

需要注意的是，即使后续配置覆盖了之前的设置，之前文件中的无效配置仍可能产生解析警告。

官方文档对此有明确说明。

## 三、问题原因：One Dark 主题名称不匹配

根据报错：

```text
theme "One Dark" not found
```

可以确定，Ghostty 在加载配置时尝试解析名为 `One Dark` 的主题，但没有在指定路径找到对应文件。

Ghostty 支持通过主题名称引用内置主题：

```ini
theme = Catppuccin Mocha
```

也支持引用自定义主题。

如果按照名称引用，Ghostty 会在预定义的主题目录中寻找匹配文件。主题文件名称必须与所配置的名称一致。

这与 VS Code、JetBrains IDE 中通过插件名称或显示名称选择主题的机制有所不同。

Ghostty 不会自动将 `One Dark` 解析为其他名称相近的主题。

而在 Ghostty 的主题资源中，存在一个名称非常接近的主题：

```text
Atom One Dark
```

其主题文件可以在这里查看：

[Atom One Dark — iTerm2 Color Schemes](https://github.com/mbadolato/iTerm2-Color-Schemes/blob/master/ghostty/Atom%20One%20Dark)

它包含完整的终端 ANSI Palette、背景色、前景色以及光标颜色。

例如：

```ini
background = #21252b
foreground = #abb2bf
cursor-color = #abb2bf
cursor-text = #21252b
```

因此，对于希望继续使用经典 One Dark 配色的用户，`Atom One Dark` 是值得优先检查的替代主题。

当然，是否可用仍应以本机实际安装的主题列表为准。

Ghostty 官方也提供了主题名称与自定义主题文件的详细说明：[Ghostty Color Theme](https://ghostty.org/docs/features/theme)。

## 四、实际排查与修复步骤

整个排查过程相对简单。

### Step 1：检查 cmux 内置主题

首先确认 cmux 当前能够识别哪些主题。

```bash
cmux themes list | grep -i "One Dark"
```

`cmux themes list` 是 cmux 官方支持的 CLI 命令，用于列出可用主题。

如果输出中包含：

```text
Atom One Dark
```

则说明该主题已经可以被 cmux 识别。

也可以直接进入交互式主题选择器：

```bash
cmux themes
```

通过预览选择需要的主题。

从排障角度看，CLI 查询更直接，因为它可以快速检查所需主题名称是否存在。

### Step 2：检查 Ghostty 配置中的主题引用

接下来定位哪个配置文件引用了错误的主题名称。

可以执行：

```bash
grep -HnE '^[[:space:]]*theme[[:space:]]*=' \
  "$HOME/.config/ghostty/config" \
  "$HOME/.config/ghostty/config.ghostty" \
  "$HOME/Library/Application Support/com.mitchellh.ghostty/config" \
  "$HOME/Library/Application Support/com.mitchellh.ghostty/config.ghostty" \
  "$HOME/Library/Application Support/com.cmuxterm.app/config.ghostty" \
  2>/dev/null
```

这条命令会：

1. 检查常用的 Ghostty 和 cmux 配置路径。
2. 搜索有效的 `theme = ...` 配置。
3. 输出匹配的文件路径和行号。
4. 忽略不存在的配置文件所产生的错误。

如果发现：

```ini
theme = One Dark
```

则需要根据第一步查询到的实际主题名称进行修正。

例如：

```ini
theme = Atom One Dark
```

或者使用其他已安装的主题：

```ini
theme = Catppuccin Mocha
```

如果不需要强制指定主题，也可以删除或注释这个配置项：

```ini
# theme = One Dark
```

此时 cmux 会根据剩余配置和默认主题机制决定终端配色。

**本次问题在这一阶段就得到了解决，没有继续进入应用资源完整性检查或重新安装流程。**

### Step 3：重新加载配置

修改完成后，可以执行：

```bash
cmux reload-config
```

也可以使用快捷键：

```text
Cmd + Shift + ,
```

cmux 会重新加载相关配置，不需要完全退出应用。

如果配置中的主题名称有效，且对应主题资源存在，原来的 `theme not found` 错误就不应再出现。

官方文档确认了 `cmux reload-config` 的使用方式。

## 五、如果问题依然存在怎么办？

如果修改主题名称后仍然出现错误，可以进一步检查 cmux 的 Ghostty 资源目录。

执行：

```bash
ls -ld \
  "/Applications/cmux.app/Contents/Resources/ghostty/themes"
```

如果目录存在，可以搜索相关主题：

```bash
find \
  "/Applications/cmux.app/Contents/Resources/ghostty/themes" \
  -maxdepth 1 \
  -iname "*one*dark*"
```

这能够帮助判断：

- 应用是否包含相应的主题资源。
- 主题文件名称是否与配置一致。
- 是否存在大小写或命名差异。

如果主题目录不存在，或者预期的主题文件缺失，才需要进一步调查 cmux 的安装完整性、资源路径或版本打包问题。

本次实际没有遇到这种情况。

## 六、这是不是 cmux 0.65.1 的 Bug？

排查过程中，我也查看了 cmux 的 GitHub Release 和相关 Pull Request。

发现一个比较有意思的改动：

[PR #18271 — Filter pathless cmux-owned Ghostty diagnostics](https://github.com/manaflow-ai/cmux/pull/18271)

该 PR 于 2026 年 10 月 7 日合并。

它修复了 cmux 在处理 Ghostty 配置诊断信息时的一类误报问题。

例如，cmux 自己使用的：

```ini
sidebar-font-size = 13
surface-tab-bar-font-size = 12
```

此前可能被 Ghostty 识别为未知字段，从而触发不必要的配置警告。

开发者通过改进诊断信息过滤逻辑，避免了这些由 cmux 自身配置字段导致的误报。

不过，这和本次遇到的情况存在区别。

本次错误信息明确指向：

```text
theme "One Dark" not found
```

并且提供了具体的主题文件查找路径。

这说明配置解析器确实尝试加载该主题，但没有找到匹配的资源。

因此，**目前没有证据表明本次问题由 cmux 0.65.1 的版本缺陷直接引起。**

从排查结果看，主题名称与实际可用主题之间的不匹配，是更有解释力的原因。

## 七、延伸：如何更方便地管理 cmux 主题？

cmux 自身提供了主题管理 CLI，因此日常切换主题不一定需要手动修改配置文件。

例如，将主题设置为 Atom One Dark：

```bash
cmux themes set "Atom One Dark"
```

分别设置明暗主题：

```bash
cmux themes set \
  --light "Catppuccin Latte" \
  --dark "Atom One Dark"
```

清除 cmux 专属主题覆盖：

```bash
cmux themes clear
```

需要注意，`themes clear` 只负责清除 cmux 的主题覆盖设置，不会自动修复 Ghostty 共享配置中已经存在的无效主题名称。

此外，也可以自行创建主题文件：

```bash
mkdir -p ~/.config/ghostty/themes
```

然后将自定义主题保存到该目录：

```text
~/.config/ghostty/themes/My Custom Theme
```

之后便可以通过：

```ini
theme = My Custom Theme
```

引用该主题。

对于同时使用 Ghostty 和 cmux 的用户，我更倾向于将共享的字体、主题和配色设置放在：

```text
~/.config/ghostty/config
```

而将 cmux 独有的参数保留在：

```text
~/Library/Application Support/com.cmuxterm.app/config.ghostty
```

这样可以尽量避免共享配置与应用专属配置之间的冲突。

## 八、总结

这次排查的是一个比较典型的终端配置兼容性问题。

在 cmux 0.65.1 中，启动时出现：

```text
Ghostty 配置错误
theme "One Dark" not found
```

排查路径可以归纳为：

**检查主题名称 → 查找实际配置来源 → 修正主题引用 → 重新加载配置。**

对于类似问题，优先使用：

```bash
cmux themes list
```

确认主题名称，再检查：

```text
~/.config/ghostty/config
```

以及：

```text
~/Library/Application Support/com.cmuxterm.app/config.ghostty
```

通常能够快速定位问题。

这次也说明，在终端应用依赖第三方渲染引擎的架构下，理解配置文件的加载顺序、主题资源的查找路径，以及应用自身的覆盖机制，比直接重新安装软件更有助于准确排障。

最终，问题在配置检查阶段就得到了解决，无需重装 cmux，也不需要降级版本。

### 参考资料

- [cmux GitHub Repository](https://github.com/manaflow-ai/cmux)
- [cmux v0.65.1 Release](https://github.com/manaflow-ai/cmux/releases/tag/v0.65.1)
- [cmux Customizing Appearance](https://github.com/manaflow-ai/cmux/blob/v0.65.1/docs/customizing-appearance.md)
- [Ghostty Color Theme Documentation](https://ghostty.org/docs/features/theme)
- [Atom One Dark Theme](https://github.com/mbadolato/iTerm2-Color-Schemes/blob/master/ghostty/Atom%20One%20Dark)
- [cmux PR #18271 — Ghostty Configuration Diagnostics](https://github.com/manaflow-ai/cmux/pull/18271)