docs: clarify file-backed secret refs · openclaw/openclaw@36e88f5
steipete
·
2026-05-17
·
via Recent Commits to openclaw:main
| Original file line number | Diff line number | Diff line change |
|---|
@@ -203,6 +203,41 @@ Define providers under `secrets.providers`:
|
203 | 203 | </Accordion> |
204 | 204 | </AccordionGroup> |
205 | 205 | |
| 206 | +## File-backed API keys |
| 207 | + |
| 208 | +Do not put `file:...` strings in the config `env` block. The `env` block is |
| 209 | +literal and non-overriding, so `file:...` is not resolved. |
| 210 | + |
| 211 | +Use a file SecretRef on a supported credential field instead: |
| 212 | + |
| 213 | +```json5 |
| 214 | +{ |
| 215 | + secrets: { |
| 216 | + providers: { |
| 217 | + xai_key_file: { |
| 218 | + source: "file", |
| 219 | + path: "~/.openclaw/secrets/xai-api-key.txt", |
| 220 | + mode: "singleValue", |
| 221 | + }, |
| 222 | + }, |
| 223 | + }, |
| 224 | + models: { |
| 225 | + providers: { |
| 226 | + xai: { |
| 227 | + apiKey: { source: "file", provider: "xai_key_file", id: "value" }, |
| 228 | + }, |
| 229 | + }, |
| 230 | + }, |
| 231 | +} |
| 232 | +``` |
| 233 | + |
| 234 | +For `mode: "singleValue"`, the SecretRef `id` is `"value"`. For |
| 235 | +`mode: "json"`, use an absolute JSON pointer such as |
| 236 | +`"/providers/xai/apiKey"`. |
| 237 | + |
| 238 | +See [SecretRef credential surface](/reference/secretref-credential-surface) for |
| 239 | +the config fields that accept SecretRefs. |
| 240 | + |
206 | 241 | ## Exec integration examples |
207 | 242 | |
208 | 243 | <AccordionGroup> |
|
| Original file line number | Diff line number | Diff line change |
|---|
@@ -36,6 +36,38 @@ Two equivalent ways to set inline env vars (both are non-overriding):
|
36 | 36 | } |
37 | 37 | ``` |
38 | 38 | |
| 39 | +The config `env` block accepts literal string values only. It does not expand |
| 40 | +`file:...` values; for example, `XAI_API_KEY: "file:secrets/xai-api-key.txt"` |
| 41 | +is passed to providers as that exact string. |
| 42 | + |
| 43 | +For file-backed provider keys, use a SecretRef on the credential field that |
| 44 | +supports it: |
| 45 | + |
| 46 | +```json5 |
| 47 | +{ |
| 48 | + secrets: { |
| 49 | + providers: { |
| 50 | + xai_key_file: { |
| 51 | + source: "file", |
| 52 | + path: "~/.openclaw/secrets/xai-api-key.txt", |
| 53 | + mode: "singleValue", |
| 54 | + }, |
| 55 | + }, |
| 56 | + }, |
| 57 | + models: { |
| 58 | + providers: { |
| 59 | + xai: { |
| 60 | + apiKey: { source: "file", provider: "xai_key_file", id: "value" }, |
| 61 | + }, |
| 62 | + }, |
| 63 | + }, |
| 64 | +} |
| 65 | +``` |
| 66 | + |
| 67 | +See [Secrets Management](/gateway/secrets) and the |
| 68 | +[SecretRef credential surface](/reference/secretref-credential-surface) for |
| 69 | +supported fields. |
| 70 | + |
39 | 71 | ## Shell env import |
40 | 72 | |
41 | 73 | `env.shellEnv` runs your login shell and imports only **missing** expected keys: |
@@ -100,6 +132,8 @@ OpenClaw supports two env-driven patterns:
|
100 | 132 | - SecretRef objects (`{ source: "env", provider: "default", id: "VAR" }`) for fields that support secrets references. |
101 | 133 | |
102 | 134 | Both resolve from process env at activation time. SecretRef details are documented in [Secrets Management](/gateway/secrets). |
| 135 | +The config `env` block itself does not resolve SecretRefs or `file:...` |
| 136 | +shorthand values. |
103 | 137 | |
104 | 138 | ## Path-related env vars |
105 | 139 | |
|
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。
