Feishu 配好了，Hermes Gateway 却一启动就崩：RedactingFormatter 没导入造成的假象

有些 Gateway 问题看起来像平台配置错了。

比如 Feishu / Lark 没收到消息，你可能会先怀疑：

App ID / App Secret 错了；
回调 URL 不通；
事件订阅没开；
机器人权限不够；
网络代理有问题。

但 NousResearch/hermes-agent issue #8173 里的情况更直接：Gateway 进程启动阶段就崩了，根本还没走到 Feishu 收消息那一步。

错误核心是：

NameError: name 'RedactingFormatter' is not defined

也就是说，gateway/run.py 使用了 RedactingFormatter，但没有 import。

表面现象：Feishu 配好了，但消息进不来

issue 的描述很典型：配置了 Feishu / Lark gateway 后，服务启动失败，launch agent 反复重启。

用户看到的外部现象可能是：

Feishu configured but not receiving messages

但这句话容易误导。

因为消息不是“收到了但处理失败”，而是 Gateway 根本没稳定跑起来。

排查时应该先看：

~/.hermes/logs/gateway.error.log

如果里面出现：

NameError: name 'RedactingFormatter' is not defined

就不是 Feishu 平台配置优先级最高了。

真正崩溃点：formatter 使用了，但没导入

issue 指向的代码路径是 gateway/run.py。

里面有类似逻辑：

_stderr_handler.setFormatter(
    RedactingFormatter('%(levelname)s %(name)s: %(message)s')
)

这个 formatter 的作用通常是日志脱敏：把 token、key、secret 这类敏感内容从日志中遮掉。

设计本身没问题。

问题是当前文件没有导入：

from agent.redact import RedactingFormatter

于是 Gateway 一启动，执行到日志 handler 初始化时就炸。

这个阶段比平台 adapter 初始化更早。

所以你后面怎么改 Feishu event subscription、callback URL、bot 权限，都不会改变这个 NameError。

为什么这个 bug 容易被误判成平台问题？

因为触发场景往往是“配置 Feishu / Lark 后启动 Gateway”。

用户自然会把因果理解成：

Feishu 配置有问题 → Gateway 不收消息

但实际链路是：

Gateway 启动日志 handler
→ 需要 RedactingFormatter
→ 名字没定义
→ 进程退出
→ launch agent 重启
→ Feishu 当然收不到消息

所以问题不是：

Feishu message delivery failed

而是：

Gateway process cannot stay alive

排查方向完全不同。

复现路径

按 issue 的步骤：

1. 配置 Hermes gateway，启用 Feishu / Lark； 2. 启动或重启 gateway service； 3. Gateway 在启动阶段崩溃； 4. 查看：

   ~/.hermes/logs/gateway.error.log

5. 看到：

   NameError: name 'RedactingFormatter' is not defined

如果你使用的是 systemd、launchd 或其他守护方式，还会看到服务不断重启。

这时“服务在跑吗”比“Feishu 收到消息了吗”更重要。

临时修复：补上 import

issue 里本地验证的修复是，在 gateway/run.py 中加入：

from agent.redact import RedactingFormatter

补上后，Gateway 能继续启动。

后续评论也指出，这个修复已经在 main 上通过 commit 8a48c58b 合入，提交信息为：

fix(gateway): add missing RedactingFormatter import

并且相关修复还添加了 startup regression test：

tests/gateway/test_runner_startup_failures.py

这点很重要：这种 bug 不应该靠人工发现。Gateway 启动路径应该有最小回归测试，至少保证 import、logging setup、runner bootstrap 不会因为一个名字没定义直接挂掉。

duplicate 线索：#8044、#8090、#8091、#8103、#8137、#8178

#8173 不是孤立报告。

评论里提到它和多个 canonical / duplicate 线程有关：

#8044：canonical issue 方向之一；
#8090 / #8091：同类 RedactingFormatter crash 报告；
#8103：提到 fix merged；
#8137：实现跟进 PR 线索；
#8178：也涉及同类修复讨论。

对普通用户来说，不需要追完整 issue 图谱。

关键结论是：

如果你当前版本仍然因为 RedactingFormatter NameError 崩溃，先升级到包含 8a48c58b / #8103 修复的版本，或本地补 import。

不要和 python-socks 问题混在一起

issue 里还有一个备注：补上 RedactingFormatter import 后，用户在 SOCKS proxy 环境下又遇到 Lark websocket 需要 python-socks 的问题。

这是另一个层次的问题。

要拆开：

问题 A：Gateway 启动即崩

症状：

NameError: name 'RedactingFormatter' is not defined

修复：

from agent.redact import RedactingFormatter

问题 B：Gateway 能启动，但 Lark websocket 代理不通

可能涉及：

python-socks
SOCKS proxy
websocket transport

这不是 #8173 的核心。

如果 Gateway 已经能稳定运行，但消息平台连接失败，再继续查代理依赖。

排查清单：先确认 Gateway 是否活着

遇到“Feishu 配好了但没响应”，不要直接重配平台。

先看这几项。

1. 看 Gateway 错误日志

tail -100 ~/.hermes/logs/gateway.error.log

查找：

RedactingFormatter
NameError

2. 看进程是否反复退出

ps aux | grep hermes

如果用了 systemd：

systemctl status hermes-gateway
journalctl -u hermes-gateway -n 100 --no-pager

如果用了 macOS launch agent，就看对应 launchd 日志和 Hermes logs。

3. 确认当前代码是否已有 import

在源码目录：

grep -n "RedactingFormatter" gateway/run.py
grep -n "from agent.redact import RedactingFormatter" gateway/run.py

如果只有使用，没有 import，就是这个坑。

对 DeepAI API 中转站用户的边界说明

如果你用 Hermes Gateway 接消息平台，再把消息交给 DeepAI API 中转站或其他 OpenAI-compatible API，链路大概是：

Feishu / Lark → Hermes Gateway → Agent → Provider → DeepAI / OpenAI-compatible API

#8173 发生在第一段 Gateway 启动阶段。

也就是说：

消息还没进 Agent；
provider 还没初始化；
DeepAI Base URL 还没被请求；
API Key 和模型名还没参与。

所以这个问题不能通过更换：

https://api.deepai.wang/v1

或更换模型解决。

正确顺序是：

1. 先让 Gateway 进程稳定启动； 2. 再确认 Feishu / Lark adapter 能连接； 3. 再查 Agent 和模型 API 层。

DeepAI 的角色只在第三步之后才出现。

FAQ

Feishu 没收到消息，是不是 App Secret 错了？

不一定。先查 gateway.error.log。如果 Gateway 因 RedactingFormatter NameError 启动失败，Feishu 配置再正确也没用。

`RedactingFormatter` 是干什么的？

它通常用于日志脱敏，避免 token、secret、API key 原样写进日志。

本地怎么快速修？

在受影响版本的 gateway/run.py 补：

from agent.redact import RedactingFormatter

更推荐升级到包含相关修复的版本。

`python-socks` 也要装吗？

那是另一个 SOCKS proxy / websocket 问题。先确认 Gateway 不再因为 RedactingFormatter 崩溃，再处理代理依赖。

DeepAI API 中转站会导致这个问题吗？

不会。这个错误发生在 Gateway 启动阶段，远早于模型 API 调用。

总结

#8173 的核心不是 Feishu，也不是 DeepAI，更不是模型能力。

它是一个非常朴素的启动期 Python 错误：

NameError: name 'RedactingFormatter' is not defined

排查这类 Gateway 问题时，先确认进程是否活着，再谈平台配置。

否则你可能会在 Feishu 后台来回改权限、重配事件订阅、检查回调 URL，最后才发现服务其实从一开始就没跑起来。