diff --git a/hermes/shazhou-family-onboard/references/00-self-unbind.md b/hermes/shazhou-family-onboard/references/00-self-unbind.md
index 1a2a327..3f132f5 100644
--- a/hermes/shazhou-family-onboard/references/00-self-unbind.md
+++ b/hermes/shazhou-family-onboard/references/00-self-unbind.md
@@ -38,6 +38,34 @@ security:
 
 说明：agent 需要看到完整的 token/key 才能正确配置和调试。
 
+⚠️ **已知 bug**：`agent/redact.py` 在 import 时就读取环境变量，导致 config.yaml 的配置不生效。需要手动 patch 源码：
+
+打开 `~/.hermes/hermes-agent/agent/redact.py`，找到顶部的：
+
+```python
+_REDACT_ENABLED = os.getenv("HERMES_REDACT_SECRETS", "").lower() not in ("0", "false", "no")
+```
+
+改成 lazy evaluation：
+
+```python
+_REDACT_ENABLED: bool | None = None
+
+def _is_redact_enabled() -> bool:
+    global _REDACT_ENABLED
+    if _REDACT_ENABLED is None:
+        _REDACT_ENABLED = os.getenv("HERMES_REDACT_SECRETS", "").lower() not in (
+            "0", "false", "no", "off",
+        )
+    return _REDACT_ENABLED
+```
+
+然后把文件中所有直接读 `_REDACT_ENABLED` 的地方改为调用 `_is_redact_enabled()`。
+
+验证 patch 是否生效：
+
+    grep '_REDACT_ENABLED: bool' ~/.hermes/hermes-agent/agent/redact.py
+
 ### 3. 关闭 Tirith 策略引擎
 
 ```yaml