Hermes Agent 启动报 Invalid key: c-S-c？prompt_toolkit 快捷键崩溃排错指南

如果你安装或升级 Hermes Agent 之后，运行：

hermes

或：

hermes chat

刚看到 banner，CLI 就直接退出，并打印：

Error: Invalid key: c-S-c

那这大概率不是 API Key、模型、网络或配置文件的问题，而是 Hermes CLI 注册了一个 prompt_toolkit 不支持的快捷键字符串：c-S-c。

这篇文章基于 NousResearch/hermes-agent issue #19903，整理一个典型的 CLI 启动崩溃 / prompt_toolkit keybinding 排错案例。

适合搜索关键词：Hermes Agent Invalid key c-S-c、prompt_toolkit Invalid key c-S-c、Hermes CLI crash on startup、hermes chat 启动崩溃、Ctrl Shift C prompt_toolkit invalid key。

先给结论：这是快捷键绑定问题，不是模型调用问题

issue #19903 里的核心报错是：

Error: Invalid key: c-S-c

问题位置指向 Hermes CLI 中类似这样的绑定：

@kb.add('c-S-c')  # Ctrl+Shift+C

它本意是处理 Ctrl+Shift+C：在很多 Linux 终端里，Ctrl+Shift+C 是复制快捷键，开发者希望不要把它当成 Ctrl+C 中断。

但 prompt_toolkit 并不接受 c-S-c 这种带 Shift 的 keybinding 字符串。结果就是：TUI 初始化 key bindings 时直接抛错，Hermes 还没进入聊天界面就崩溃。

典型现象

你可能遇到这些表现：

hermes 启动后立即崩溃；
hermes chat 同样崩溃；
banner 或工具面板刚渲染出来就退出；
终端显示 Invalid key: c-S-c；
非交互模式反而可能正常，例如 hermes -z "Reply exactly: Hermes works." 能跑通。

这个细节很关键：如果非交互模式可用，说明模型、API、网络、配置大概率没问题，问题集中在交互式 TUI 的 keybinding 初始化。

影响平台：不只 macOS，也可能影响 Linux / SSH / ARM

issue 和评论里提到的环境包括：

macOS Terminal.app；
Apple Silicon / Mac Mini M4；
Arch Linux；
fish shell；
Wayland；
Kitty / Alacritty；
Raspberry Pi 4B ARM64；
从 macOS Terminal 通过 SSH 连接远程机器。

所以不要把它误判为“某个终端模拟器坏了”。根因在 keybinding 字符串本身，而不是你按了某个快捷键。

只要 Hermes 版本里还注册了 @kb.add('c-S-c')，启动时就可能直接失败。

为什么 Ctrl+Shift+C 会导致启动崩溃？

prompt_toolkit 对 keybinding 名称有自己的格式要求。常见可用写法类似：

c-c
c-d
escape
enter

但 c-S-c 这种“Ctrl + Shift + C”的表示并不是它支持的 key 名称。

因此，问题不是用户真的按了 Ctrl+Shift+C，而是程序启动时注册这个快捷键就失败了。

这也是为什么 Hermes 可能在你什么都没输入时就崩溃。

立即判断是不是这个问题

可以做三个检查。

1. 看报错文本

如果有：

Invalid key: c-S-c

基本就命中了。

2. 测试非交互模式

运行：

hermes -z "Reply exactly: Hermes works."

如果它能返回：

Hermes works.

而 hermes / hermes chat 崩溃，那说明 TUI 层更可疑。

3. 搜索源码

如果你是源码安装或本地有 Hermes 目录，可以搜索：

rg -n "c-S-c|prompt_toolkit|@kb.add" ~/.hermes/hermes-agent

如果看到类似：

cli.py:10487: @kb.add('c-S-c')

就和 issue #19903 的根因一致。

临时 workaround：删除或注释这个 no-op 绑定

issue 里给出的临时修复很简单：删除或注释掉这段绑定。

类似：

-        @kb.add('c-S-c')  # Ctrl+Shift+C
-        def handle_ctrl_shift_c(event):
-            return
+        # Disabled: prompt_toolkit does not support c-S-c key name

为什么可以删？因为这个 handler 本身是 no-op，只是想让终端原生处理复制操作。删除这个绑定通常不会影响 Hermes 的核心功能。

不过注意：如果你不是源码安装，不建议随便改系统文件。优先升级到包含修复的版本。

推荐修复：升级到已移除无效绑定的版本

#19903 已 closed/completed，评论中提到当前 main 中相关 invalid binding 已被移除，只保留解释性注释；相关讨论指向 #19919。

因此最稳的处理方式是：

1. 升级 Hermes Agent； 2. 确认当前安装版本不再包含 @kb.add('c-S-c')； 3. 再启动 hermes 或 hermes chat。

如果升级后仍报同样错误，说明你可能还在运行旧安装路径里的 CLI 文件。可以检查：

which hermes

以及实际源码路径里是否仍有 c-S-c。

不要误判成这些问题

这个错误很容易被误判。

误判方向	为什么不是
API Key 错了	报错发生在 TUI 初始化阶段，还没调用模型
模型不可用	非交互模式可能能正常返回
终端编码问题	报错是 keybinding 名称无效，不是 UnicodeEncodeError
Ctrl+C 被按坏了	用户没按键也会触发，因为启动时注册失败
网络问题	本地 CLI 初始化就崩溃

所以看到 Invalid key: c-S-c 时，先查 CLI keybinding，而不是去改模型配置。

和 DeepAI API 中转站有什么关系？

这个问题本身和 DeepAI API 中转站没有直接关系。

DeepAI API 中转站适合解决的是 OpenAI-compatible 模型接入问题，例如：

统一 Base URL；
统一 API Key；
管理多模型；
在 Cherry Studio、Cline、Dify、Open WebUI 等工具里接入兼容 API。

但 Invalid key: c-S-c 是 Hermes CLI 本地 TUI 启动阶段的 prompt_toolkit keybinding 问题。它发生在模型请求之前，因此换 API 网关、换 Key、换模型都不会修复。

正确做法是升级 Hermes 或移除无效 keybinding。

FAQ

为什么我没按 Ctrl+Shift+C，也会报错？

因为程序启动时注册 c-S-c keybinding 就失败了，不需要用户真的按下这个快捷键。

非交互模式能用，说明什么？

说明模型调用链可能正常，问题更可能在交互式 TUI / prompt_toolkit 层。

注释掉 `@kb.add('c-S-c')` 会影响复制吗？

通常不会。Ctrl+Shift+C 复制本来就是终端模拟器处理的行为，Hermes 里的这个 handler 是 no-op。

macOS 上也会受影响吗？

会。issue 中 macOS Terminal.app、Linux、SSH、Raspberry Pi 等环境都有类似复现。

这个问题已经修复了吗？

#19903 已 closed/completed，评论提到当前 main 已移除 invalid binding。建议升级并确认本地实际运行的 Hermes 路径不再包含 c-S-c。

总结

Hermes Agent 启动报：

Error: Invalid key: c-S-c

不是 API、模型或网络问题，而是 CLI 交互界面注册了 prompt_toolkit 不支持的 Ctrl+Shift+C keybinding。

排查顺序很简单：

1. 确认报错是否包含 Invalid key: c-S-c； 2. 测试 hermes -z 非交互模式； 3. 搜索源码里是否有 @kb.add('c-S-c')； 4. 升级 Hermes，或临时注释掉这个 no-op 绑定。

一句话总结：如果 Hermes 还没进聊天界面就崩溃，先别改 API Key，先查 prompt_toolkit 快捷键绑定。