10. 配置、主题与终端

终端支持

让全屏 TUI 能在普通终端、tmux、SSH 和有限色深里用。先跑 Doctor；它给出具名修复时，一次只应用一项。

诊断

在会话里：

/doctor

别名：/terminal-setup、/terminal-check、/terminal-info。

若 Matcha 无法启动，在 shell 里：

matcha doctor
matcha doctor --json

报告可以列出问题，退出码仍为 0。管道里的 matcha doctor --json 仍报告同样的颜色能力。

/doctor 能看到独立命令看不到的现场会话细节：全屏是否真的开着、通知/焦点跟踪，以及沙箱配置冲突。

/doctor fix 列出此处可用的自动修复。然后应用一项：

/doctor fix tmux-clipboard
matcha doctor fix dcs-passthrough --yes

具名 id 与短句柄都行（tmux-clipboard 或 terminal.tmux-clipboard）。

自动修复 tmux 与 SSH

发现项存在时，Doctor 可以持久写入这些：

句柄	写入内容
`tmux-clipboard`	`set -g set-clipboard on`
`dcs-passthrough`	`set -wg allow-passthrough on`
`tmux-extended-keys`	`set -g extended-keys on`
`tmux-truecolor`	`set -as terminal-features ",*:RGB"`
`ssh-wrap`	本机 shell 别名，让 `ssh` 走 `matcha wrap`

tmux 修复只改托管 tmux 服务那台机器上的持久配置（含远端会话）。普通 tmux 用 $HOME/.tmux.conf。Byobu-tmux 用 BYOBU_CONFIG_DIR，路径缺失或不安全时拒绝猜测。Matcha 保留文件的换行和权限，备份已有文件，并拒绝冲突赋值。

扫描看的是直接的全局赋值。被 source 的文件、条件语句和插件请自行核对。

颜色

健康的全屏环境会显示 color truecolor 与 themes all。

在 tmux 里要分清两件事：

Matcha 发出什么（Doctor 里的 color）。
tmux 放行什么。若已连接的客户端未标 RGB，tmux 可以把 24 位色改写到只剩八色。即使 color 显示 truecolor，主题也会发灰。该发现项是 terminal.tmux-truecolor。

真彩色修复之后：重新加载 tmux，再 detach/reattach。只重新加载修不好客户端；只重新 attach 不会拿到新的服务选项。

NO_COLOR 关闭颜色。Matcha Night / Matcha Day 在 256 色终端上仍可用；Tokyo Night 和其它带色调的色板需要真彩色。见「主题」。

剪贴板与 OSC 52

/doctor 的 Clipboard 最多列出三条路径：

路径	含义
native	本机系统剪贴板
tmux	在 tmux 内时的 tmux 粘贴缓冲
OSC 52	可穿过 tmux、容器或 SSH 的转义序列

启动前设置 MATCHA_CLIPBOARD_NO_OSC52=1 可关闭 OSC 52（未实现它的终端可能把载荷当文本倒出来）。native 与 tmux 路径保持原样。之后 /doctor 会显示 osc 52 off。

每次复制也会写入 ~/.matcha/last-copy.txt（或 MATCHA_COPY_FILE）。投递未核实时，toast 会点出该文件。/copy <file> 会有意写到那里。

Wayland：较旧的合成器可能需要终端保持焦点，直到复制 toast 出现。MATCHA_CLIPBOARD_NO_DATA_CONTROL=1 会强制走命令行剪贴板工具。

全屏、复用器与按键

Zellij 与 tmux 控制模式常常让 Matcha 留在行内。在 ~/.matcha/pager.toml 设置 [terminal] alt_screen（auto / always / never），或传 matcha --no-alt-screen 确认行内可用。对 /theme 这类命令，--no-alt-screen 仍算全屏。

Zellij 0.41+：使用 Unlock-First（不冲突）预设（Ctrl+o, c, Change Mode Behavior）。Ctrl+g 回到 Zellij 自己的控制。

WezTerm：若 Ctrl+Enter 无法插入，启用 Kitty keyboard protocol（Doctor 里的 terminal.wezterm-kitty）。Apple Terminal 用 Ctrl+O 表示该组合。

VS Code / Cursor / Windsurf / Zed：Shift+Enter 可能变成 Enter。换行用 Alt+Enter（terminal.newline-fallback）。

鼠标报告：Apple Terminal 的 View → Allow Mouse Reporting；iTerm2 配置里 Enable mouse reporting。

GNU screen 上的 Byobu 能力有限（terminal.byobu-screen）；把 Byobu 换成它的 tmux 后端。

核对一下

在 Matcha 外跑 matcha doctor，再在里面跑 /doctor。比较颜色与剪贴板行。
在 tmux 里，若主题发灰，应用 tmux-truecolor，重新加载，detach，reattach，再跑 /doctor。
未经 wrap 的 SSH 上，复制一条回复并打开 ~/.matcha/last-copy.txt。