常见问题

起不来

zettcode: Config key ... must be str / Unknown config keys ... —— 报错里会点名出错的键。 拼错的键会被拒绝而不是忽略，所以通常改拼写就好。完整的键见配置文件。

zettcode: No models configured —— ~/.zettcode/config.toml 至少要有一张 [[models]] 表。 可以从快速开始里的例子抄。

zettcode: no session <id> in <path> —— --resume 给的 id 不在这个工作区的存储里。会话是 按工作区隔离的：确认 -w 指向的目录和创建会话时是同一个，或者直接运行 zettcode 用 /resume 从列表里挑。

起来了但用不了

第一条请求就报连接错误。 base_url 是 OpenAI 兼容 API 的根地址，不是聊天网页， 也不是完整的 completion 路径。DeepSeek 使用 https://api.deepseek.com，其他接入点可能 需要 /v1。按连接测试使用同一个模型和 key 验证，再检查 API 余额、权限和代理设置。

模型名被拒绝。 用接入点期望的 id，而不是某个界面里显示的名字 —— display_model 只是头部 显示用的，随便写。

第一帧出得很慢。 模型客户端延迟创建，但配置、存储和插件加载仍然发生在启动阶段。 macOS/Linux 可以用 time zettcode --dry-run，PowerShell 可以用 Measure-Command { zettcode --dry-run } 测量本地启动流程。它会绘制一帧后退出， 不是 API 连通性检查。先比较关闭第三方插件后的时间，不要直接把延迟归因于模型或终端。

界面

颜色不对，或者文字看不清。 用 /theme light 或 /theme dark。启动时 ZettCode 会问终端 背景色是什么；终端不回答、中间隔了 multiplexer、或者 TERM 报错了颜色深度，都可能让它判断 失误。/theme 对本次运行生效，~/.zettcode/theme.toml 则是一劳永逸。

用久了显示乱掉。 按 Ctrl-L 重画。窗口大小变化是被处理好的，但别的程序绕过 ZettCode 直接 往终端写，这个没法处理。

在终端里选不中 / 复制不了。 ZettCode 在你松开拖动时自己复制选区，所以绕开了终端自带的选择。 想用终端自带的，按住它的修饰键（Shift 或 Option）再拖。

粘贴图片没反应。 图片粘贴需要桌面剪贴板，所以 macOS 可用，Linux 需要装 wl-paste 或 xclip，Windows 暂不支持。把图片当文本粘贴的终端（比如 VS Code 的）我们也能识别。

会话

对话丢了。 所有内容都是边发生边追加到 ~/.zettcode/sessions/<工作区键>/<会话 id>/data.jsonl，所以它还在：/resume 会列出这个 工作区最近的会话（新的在前）。同一目录下的 metadata.jsonl 存着标题。

恢复出来的会话不一样。 标题和 token 统计来自元数据索引，对话来自 JSONL 树。如果崩溃截断了 文件的最后一行，那一行会被忽略，其余部分照常加载。

对话内容和我说的话不一致。 模型看到的是它该看到的，屏幕显示的是你打的内容。@skill 和 图片芯片会为请求展开、但为你保留成芯片，所以恢复会话时看到的是芯片。

上下文与花费

ctx 很高而且在涨。 打开 /context：百分比是窗口内部的占比，所以最大的那一行就是占地方 的东西 —— 通常是工具输出。/compact 可以不等触发线直接总结。

缓存命中率很低。 provider 缓存的是前缀，所以请求开头任何变化都会打断它：不同的系统提示、 不同的工具集合、不同的模型。切换模型、压缩和修改指令可能让比例下降，缓存寿命也由供应商 决定，没有通用的“正常百分比”。计算方式和例子见读懂统计。

跑了我不想跑的命令。 先检查之前的审批选择：a 给出较宽的允许范围，p 会在当前进程 中记住精确命令，重启会清除这些记忆。这个审批针对内置 shell 工具，不覆盖所有文件编辑或 MCP 工具。ZettCode 不提供工具沙箱，应使用版本控制并检查 diff。

Skills、MCP 与插件

我的 skill 没出现。 它需要是一个目录，里面有 SKILL.md，且 front matter 带 name 和 description，位置在 ~/.zettcode/skills/ 或配置的 [skills] roots 下。只有 front matter 会被索引；同名时前面的根目录优先。

MCP 服务器起不来。 它的横幅和报错都写进 ~/.zettcode/log/tui.log，因为画到屏幕上会把 画面弄乱。启动失败的服务器会在对话里被点名；常见原因是 URL 写错或连不上。

插件被跳过了。 在普通 Python 里 import 它就能看到真正的报错；ZettCode 会报出插件名并让 会话继续。两个插件不能重名，也不能占用已存在的命令名。

新版本

它提示我升级。 ZettCode 每天会在后台向 PyPI 问一次有没有新版本；启动从不等待这个请求， [update] enabled = false 可以完全关掉。查到更新的版本后，下一次启动会在对话之上弹出面板：

• Upgrade now：按当前安装方式执行升级 —— uv tool upgrade zettcode，或 pip install --upgrade zettcode —— 在后台跑。当前窗口用的还是启动时的代码，升级后需要重启。
• Skip this version：把版本记进 ~/.zettcode/update.json，这个版本不再提示，再往后的 新版本会重新提示。
• Not now（或 Esc）：什么都不写，下次启动还会就同一个版本再问一次。

提示来自那个文件而不是网络，所以离线机器不会看到任何版本相关的打扰。

退出

怎么退出？ /quit，或者在输入框为空时按 Ctrl-D。Ctrl-C 是停止正在跑的请求、请求为 空时清空草稿 —— 它不是退出。退出时会打印恢复当前会话的 zettcode --resume … 命令。