diff --git a/docs/cli/secrets.md b/docs/cli/secrets.md
index f73857f4573..990be40d6f6 100644
--- a/docs/cli/secrets.md
+++ b/docs/cli/secrets.md
@@ -82,8 +82,10 @@ openclaw secrets migrate --json | jq '{mode, changed, counters, changedFiles}'
 openclaw secrets migrate --write --json > /tmp/openclaw-secrets-migrate.json
 ```
 
-### Force a reload after updating env vars
+### Force a reload after updating gateway env visibility
 
 ```bash
-OPENAI_API_KEY="..." openclaw secrets reload
+# Ensure OPENAI_API_KEY is visible to the running gateway process first,
+# then re-resolve refs:
+openclaw secrets reload
 ```
diff --git a/docs/docs.json b/docs/docs.json
index bd796efd666..3211976230a 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1236,8 +1236,8 @@
                   "cli/qr",
                   "cli/reset",
                   "cli/sandbox",
-                  "cli/security",
                   "cli/secrets",
+                  "cli/security",
                   "cli/sessions",
                   "cli/setup",
                   "cli/skills",