docs(env): clarify .env precedence and config token note

.env.example

@@ -1,5 +1,70 @@
-# Copy to .env and fill with your Twilio credentials
-TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-TWILIO_AUTH_TOKEN=your_auth_token_here
-# Must be a WhatsApp-enabled Twilio number, prefixed with whatsapp:
-TWILIO_WHATSAPP_FROM=whatsapp:+17343367101
+# OpenClaw .env example
+#
+# Quick start:
+# 1) Copy this file to `.env` (for local runs from this repo), OR to `~/.openclaw/.env` (for launchd/systemd daemons).
+# 2) Fill only the values you use.
+# 3) Keep real secrets out of git.
+#
+# Env-source precedence for environment variables (highest -> lowest):
+# process env, ./.env, ~/.openclaw/.env, then openclaw.json `env` block.
+# Existing non-empty process env vars are not overridden by dotenv/config env loading.
+# Note: direct config keys (for example `gateway.auth.token` or channel tokens in openclaw.json)
+# are resolved separately from env loading and often take precedence over env fallbacks.
+
+# -----------------------------------------------------------------------------
+# Gateway auth + paths
+# -----------------------------------------------------------------------------
+# Recommended if the gateway binds beyond loopback.
+OPENCLAW_GATEWAY_TOKEN=change-me-to-a-long-random-token
+# Example generator: openssl rand -hex 32
+
+# Optional alternative auth mode (use token OR password).
+# OPENCLAW_GATEWAY_PASSWORD=change-me-to-a-strong-password
+
+# Optional path overrides (defaults shown for reference).
+# OPENCLAW_STATE_DIR=~/.openclaw
+# OPENCLAW_CONFIG_PATH=~/.openclaw/openclaw.json
+# OPENCLAW_HOME=~
+
+# Optional: import missing keys from your login shell profile.
+# OPENCLAW_LOAD_SHELL_ENV=1
+# OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000
+
+# -----------------------------------------------------------------------------
+# Model provider API keys (set at least one)
+# -----------------------------------------------------------------------------
+# OPENAI_API_KEY=sk-...
+# ANTHROPIC_API_KEY=sk-ant-...
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=sk-or-...
+
+# Optional additional providers
+# ZAI_API_KEY=...
+# AI_GATEWAY_API_KEY=...
+# MINIMAX_API_KEY=...
+# SYNTHETIC_API_KEY=...
+
+# -----------------------------------------------------------------------------
+# Channels (only set what you enable)
+# -----------------------------------------------------------------------------
+# TELEGRAM_BOT_TOKEN=123456:ABCDEF...
+# DISCORD_BOT_TOKEN=...
+# SLACK_BOT_TOKEN=xoxb-...
+# SLACK_APP_TOKEN=xapp-...
+
+# Optional channel env fallbacks
+# MATTERMOST_BOT_TOKEN=...
+# MATTERMOST_URL=https://chat.example.com
+# ZALO_BOT_TOKEN=...
+# OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:...
+
+# -----------------------------------------------------------------------------
+# Tools + voice/media (optional)
+# -----------------------------------------------------------------------------
+# BRAVE_API_KEY=...
+# PERPLEXITY_API_KEY=pplx-...
+# FIRECRAWL_API_KEY=...
+
+# ELEVENLABS_API_KEY=...
+# XI_API_KEY=...  # alias for ElevenLabs
+# DEEPGRAM_API_KEY=...