Agent 主题故障排查:六个最常见的坏法

1. 导入串被拒了

主题导入器对结构的校验很严,而一条在聊天软件里旅行过的字符串,通常已经被啃过:被自动换行、被长度上限截断、直引号被"智能"成弯引号。缺一个字段就可能整条失败,还未必给出有用的报错。

按升级顺序修。先回到源头,完整重新复制一次,不要手改。然后先粘进预览工具——它解析得很宽容(完整串、裸 JSON、零散色值都认),并显示识别出了哪些 token,一眼看出问题在字符串还是在导入器。如果预览读得好好的、导入器还是拒收,就别跟它吵了:Codex 教程里的安装提示词路线走外观设置应用颜色,完全绕开导入校验。

2. 亮暗模式串了

症状:浅底上浮着浅字,或者一片浅色界面里嵌着一块黑洞。原因:主题只定义了一种极性,而应用正渲染着另一种——大多数流传的主题只带一个变体。把应用的外观模式翻到和主题一致,或者去图库找它的姊妹变体;浏览页专门按深色和浅色筛,就是为这趟差事准备的。

阴险的版本:一到晚上就全不对劲。那通常是操作系统在日落时自动切换外观模式,而主题只有单变体——查一下你的应用是否跟随系统设置。要么把应用钉死在主题的极性上,要么同家族深浅各装一套,让交接发生在成对的颜色里。

3. diff 看不清了

diff 的颜色不是独立涂上去的。agent 界面通常直接拿字符串绿标 diff 新增行、拿 error 红标 diff 删除行——我们的预览如此,多数界面也如此。把这两个 token 往背景方向调(比如一次"有品位的降饱和"),review 视图就悄悄塌了。新增行看不见,查 string;删除行消失,查 error。

检验就是眯眼:对着一段 diff 眯起眼睛,两条色带都应该依然明显。不行的话,把这两个 token 的明度推离底色,直到回到正文级对比(4.5:1 附近),或者直接抄图库里任何一套现成配色的值。土办法对比度测试在自制主题教程里有全套;预览工具里那个 diff 块就是为这场彩排准备的——先粘、先看、先改,再碰真应用。

4. 我只想回默认

比你担心的短。Codex 应用:外观设置里永远留着内置预设,选一个就是出厂状态。Claude Code:跑 /theme 选回内置主题。如果改动是安装提示词做的,agent 汇报的改动清单就是你的还原清单;嫌清单麻烦,直接让 agent 恢复默认外观——一句话的事。色值主题不在别处留任何隐藏状态,这正是它在安全层级里稳坐绿色档的原因。

一个小坑:要重置的得是你真正改过的那一层。如果某个窗口的样子来自"终端 profile + ANSI 预设"这条链,重置应用毫无作用——颜色住在终端里,终端会继续照常供应。彻底迷路时的重置顺序:先应用预设,再终端 profile,最后才是注入引擎(如果装过)。

5. 终端 ANSI 和应用主题,谁说了算

桌面 agent 应用拥有自己的整个窗口,终端在那里没有投票权。Claude Code 相反——它在终端里渲染,层叠关系就重要了:它的常规主题在上层涂自己的颜色;dark-ansi / light-ansi 两个预设则反过来继承终端的 16 色 ANSI 调色板。而窗口背景,无论选哪个预设,永远归终端管。

这就解释了那种经典的翻车:浅色终端 profile 垫着深色 Claude Code 预设,或者反过来——半个界面假设一种极性,另外半个拒不配合。要么手动把两层对齐,要么干脆全押一边:配色放进终端 profile,预设用 ANSI 系,让一层说了算。

6. 这些设置到底存在哪?

粗略的地图:Codex 应用的外观存在应用自己的设置里;Claude Code 的主题选择保存在它的用户级设置中;终端配色住在各终端的 profile 里;注入皮肤的配置则在它自己的引擎里,压根不在任何外观设置内——所以卸载它是引擎的事,不是哪个设置开关(那一档见安全页)。具体文件名和路径随版本变动,所以永远以你手上版本的设置界面为准,而不是任何博客文章——包括,坦率地说,这一篇。