diff --git a/website/docs/user-guide/messaging/discord.md b/website/docs/user-guide/messaging/discord.md
index f6da7e0c4dfa6..84d8f1a74f644 100644
--- a/website/docs/user-guide/messaging/discord.md
+++ b/website/docs/user-guide/messaging/discord.md
@@ -282,7 +282,7 @@ You can run `hermes gateway` in the background or as a systemd service for persi
 
 ## Configuration Reference
 
-Discord behavior is controlled through two files: **`~/.hermes/.env`** for credentials and env-level toggles, and **`~/.hermes/config.yaml`** for structured settings. Environment variables always take precedence over config.yaml values when both are set.
+Discord behavior is controlled through two files: **`~/.hermes/.env`** for credentials (bot token) and **`~/.hermes/config.yaml`** for structured settings. Secrets stay in `.env`. For `discord.require_mention` and `discord.free_response_channels`, the adapter reads `config.yaml` when the key is set; the matching `DISCORD_*` environment variable is the fallback. That matches [Configuration Precedence](../configuration.md#configuration-precedence) for non-secret settings.
 
 ### Environment Variables (`.env`)
 
@@ -327,7 +327,7 @@ Wiring multiple Hermes profiles to reply to one another in a shared channel —
 
 ### Config File (`config.yaml`)
 
-The `discord` section in `~/.hermes/config.yaml` mirrors the env vars above. Config.yaml settings are applied as defaults — if the equivalent env var is already set, the env var wins.
+The `discord` section in `~/.hermes/config.yaml` mirrors the env vars above. For `require_mention` and `free_response_channels`, a key present under `discord:` — including defaults written on a fresh install — wins. The matching `DISCORD_*` variable is used only if that config key is unset, which is why a conflicting `.env` entry is ignored.
 
 ```yaml
 # Discord-specific settings
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/discord.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/discord.md
index 8df87a340e2c6..82457a3c6d96f 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/discord.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/discord.md
@@ -281,7 +281,7 @@ hermes gateway
 
 ## 配置参考
 
-Discord 行为通过两个文件控制：**`~/.hermes/.env`** 用于凭据和环境级开关，**`~/.hermes/config.yaml`** 用于结构化设置。当两者都设置时，环境变量始终优先于 config.yaml 的值。
+Discord 行为通过两个文件控制：**`~/.hermes/.env`** 用于凭据（机器人 token），**`~/.hermes/config.yaml`** 用于结构化设置。密钥留在 `.env`。对于 `discord.require_mention` 和 `discord.free_response_channels`，适配器在配置键已设置时读取 `config.yaml`；对应的 `DISCORD_*` 环境变量仅作回退。这与[配置优先级](../configuration.md#配置优先级)中非密钥项的规则一致。
 
 ### 环境变量（`.env`）
 
@@ -318,7 +318,7 @@ Discord 行为通过两个文件控制：**`~/.hermes/.env`** 用于凭据和环
 
 ### 配置文件（`config.yaml`）
 
-`~/.hermes/config.yaml` 中的 `discord` 部分与上述环境变量对应。config.yaml 设置作为默认值应用——如果已设置等效的环境变量，则环境变量优先。
+`~/.hermes/config.yaml` 中的 `discord` 部分与上述环境变量对应。对于 `require_mention` 和 `free_response_channels`，只要 `discord:` 下存在该键（包括全新安装写入的默认值），该值即生效；对应的 `DISCORD_*` 变量仅在该配置键未设置时使用，因此会忽略 `.env` 中的冲突项。
 
 ```yaml
 # Discord 特定设置