feat: allow inline env vars in config

docs/concepts/models.md

@@ -105,7 +105,7 @@ and an **Auth overview** section showing which providers have profiles/env/model
 
 Input
 - OpenRouter `/models` list (filter `:free`)
-- Requires OpenRouter API key from auth profiles or `OPENROUTER_API_KEY`
+- Requires OpenRouter API key from auth profiles or `OPENROUTER_API_KEY` (see [/environment](/environment))
 - Optional filters: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
 - Probe controls: `--timeout`, `--concurrency`
 

docs/environment.md

@@ -0,0 +1,60 @@
+---
+summary: "Where Clawdbot loads environment variables and the precedence order"
+read_when:
+  - You need to know which env vars are loaded, and in what order
+  - You are debugging missing API keys in the Gateway
+  - You are documenting provider auth or deployment environments
+---
+# Environment variables
+
+Clawdbot pulls environment variables from multiple sources. The rule is **never override existing values**.
+
+## Precedence (highest → lowest)
+
+1) **Process environment** (what the Gateway process already has from the parent shell/daemon).
+2) **`.env` in the current working directory** (dotenv default; does not override).
+3) **Global `.env`** at `~/.clawdbot/.env` (aka `$CLAWDBOT_STATE_DIR/.env`; does not override).
+4) **Config `env` block** in `~/.clawdbot/clawdbot.json` (applied only if missing).
+5) **Optional login-shell import** (`env.shellEnv.enabled` or `CLAWDBOT_LOAD_SHELL_ENV=1`), applied only for missing expected keys.
+
+If the config file is missing entirely, step 4 is skipped; shell import still runs if enabled.
+
+## Config `env` block
+
+Two equivalent ways to set inline env vars (both are non-overriding):
+
+```json5
+{
+  env: {
+    OPENROUTER_API_KEY: "sk-or-...",
+    vars: {
+      GROQ_API_KEY: "gsk-..."
+    }
+  }
+}
+```
+
+## Shell env import
+
+`env.shellEnv` runs your login shell and imports only **missing** expected keys:
+
+```json5
+{
+  env: {
+    shellEnv: {
+      enabled: true,
+      timeoutMs: 15000
+    }
+  }
+}
+```
+
+Env var equivalents:
+- `CLAWDBOT_LOAD_SHELL_ENV=1`
+- `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`
+
+## Related
+
+- [Gateway configuration](/gateway/configuration)
+- [FAQ: env vars and .env loading](/start/faq#env-vars-and-env-loading)
+- [Models overview](/concepts/models)

docs/gateway/configuration-examples.md

@@ -48,6 +48,10 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
 {
   // Environment + shell
   env: {
+    OPENROUTER_API_KEY: "sk-or-...",
+    vars: {
+      GROQ_API_KEY: "gsk-..."
+    },
     shellEnv: {
       enabled: true,
       timeoutMs: 15000

docs/gateway/configuration.md

@@ -91,6 +91,22 @@ Additionally, it loads:
 
 Neither `.env` file overrides existing env vars.
 
+You can also provide inline env vars in config. These are only applied if the
+process env is missing the key (same non-overriding rule):
+
+```json5
+{
+  env: {
+    OPENROUTER_API_KEY: "sk-or-...",
+    vars: {
+      GROQ_API_KEY: "gsk-..."
+    }
+  }
+}
+```
+
+See [/environment](/environment) for full precedence and sources.
+
 ### `env.shellEnv` (optional)
 
 Opt-in convenience: if enabled and none of the expected keys are set yet, CLAWDBOT runs your login shell and imports only the missing expected keys (never overrides).
@@ -1178,6 +1194,12 @@ Example:
 }
 ```
 
+Notes:
+- `agent.elevated` is **global** (not per-agent). Availability is based on sender allowlists.
+- `/elevated on|off` stores state per session key; inline directives apply to a single message.
+- Elevated `bash` runs on the host and bypasses sandboxing.
+- Tool policy still applies; if `bash` is denied, elevated cannot be used.
+
 `agent.maxConcurrent` sets the maximum number of embedded agent runs that can
 execute in parallel across sessions. Each session is still serialized (one run
 per session key at a time). Default: 1.

docs/start/faq.md

@@ -185,6 +185,19 @@ Clawdbot reads env vars from the parent process (shell, launchd/systemd, CI, etc
 
 Neither `.env` file overrides existing env vars.
 
+You can also define inline env vars in config (applied only if missing from the process env):
+
+```json5
+{
+  env: {
+    OPENROUTER_API_KEY: "sk-or-...",
+    vars: { GROQ_API_KEY: "gsk-..." }
+  }
+}
+```
+
+See [/environment](/environment) for full precedence and sources.
+
 ### “I started the Gateway via a daemon and my env vars disappeared.” What now?
 
 Two common fixes: