LeoYeAI/agent-master-skills / skills/bengii-gemini-fix
openclaw
FlaggedComprehensive guide for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway. Use when the user asks about OpenClaw setup, configuration, channel management (WhatsApp/Telegram/Discord/Slack/iMessage/etc.), model provider setup, Gateway operations, multi-agent routing, security hardening, troubleshooting, or any maintenance task related to their local OpenClaw installation. Also use when encountering errors from `openclaw` CLI commands or the Gateway daemon.
references/secrets.md
View on GitHub# OpenClaw Secrets Management Reference
## Table of Contents
- [Overview](#overview)
- [Runtime Model](#runtime-model)
- [SecretRef Contract](#secretref-contract)
- [Provider Config](#provider-config)
- [CLI Commands](#cli-commands)
- [Integration Examples](#integration-examples)
- [In-Scope Fields](#in-scope-fields)
- [Environment Variables](#environment-variables)
- [Env Var Substitution](#env-var-substitution)
- [Best Practices](#best-practices)
## Overview
OpenClaw supports external secret resolution to avoid plaintext credentials in config files. Secrets can come from environment variables, files, or external commands (1Password, Vault, sops).
## Runtime Model
- Resolution is **eager during activation**, not lazy
- Startup **fails fast** if any referenced credential cannot be resolved
- Reload uses **atomic swap**: full success or keep last-known-good
- Runtime requests read from the active in-memory snapshot
## SecretRef Contract
```json5
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
```
### source: "env"
Reads from environment variables.
```json5
{ source: "env", provider: "default", id: "OPENAI_API_KEY" }
```
- `provider` must match `^[a-z][a-z0-9_-]{0,63}$`
- `id` must match `^[A-Z][A-Z0-9_]{0,127}$`
### source: "file"
Reads from a JSON file managed by a file provider.
```json5
{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }
```
- `id` must be an absolute JSON pointer (`/...`)
- RFC6901 escaping: `~` → `~0`, `/` → `~1`
### source: "exec"
Runs a command to fetch the secret.
```json5
{ source: "exec", provider: "vault", id: "providers/openai/apiKey" }
```
- `id` must match `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
## Provider Config
```json5
{
secrets: {
providers: {
// Env provider (default, always available)
default: { type: "env" },
// File provider
filemain: {
type: "file",
path: "~/.openclaw/secrets.json",
},
// Exec provider
vault: {
type: "exec",
command: "op read op://MyVault/{id}", // {id} is replaced
timeoutMs: 10000,
shell: true,
},
},
},
}
```
### Exec Provider Examples
**1Password CLI:**
```json5
{
secrets: {
providers: {
op: {
type: "exec",
command: "op read op://MyVault/{id}",
shell: true,
},
},
},
models: {
providers: {
openai: {
apiKey: { source: "exec", provider: "op", id: "OpenAI/credential" },
},
},
},
}
```
**HashiCorp Vault CLI:**
```json5
{
secrets: {
providers: {
vault: {
type: "exec",
command: "vault kv get -field=value secret/{id}",
shell: true,
},
},
},
}
```
**sops:**
```json5
{
secrets: {
providers: {
sops: {
type: "exec",
command: "sops --decrypt --extract '[\"providers\"][\"openai\"][\"apiKey\"]' ~/.openclaw/secrets.enc.json",
shell: true,
},
},
},
}
```
## CLI Commands
```bash
openclaw secrets reload # Re-resolve refs, swap runtime snapshot
openclaw secrets audit # Scan for plaintext, unresolved refs
openclaw secrets configure # Interactive setup + SecretRef mapping
openclaw secrets apply --from <f> # Apply plan (--dry-run supported)
```
## Integration Examples
Full config with SecretRefs:
```json5
{
models: {
providers: {
openai: {
apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" },
},
},
},
channels: {
telegram: {
botToken: { source: "exec", provider: "op", id: "Telegram/BotToken" },
},
googlechat: {
serviceAccountRef: { source: "exec", provider: "vault", id: "channels/googlechat/serviceAccount" },
},
},
}
```
## In-Scope Fields
SecretRefs are supported in:
**~/.openclaw/openclaw.json:**
- `models.providers.<provider>.apiKey`
- `channels.<channel>.botToken` / `token`
- `channels.<channel>.signingSecret`
- `channels.<channel>.appToken`
- `gateway.auth.token` / `password`
- Skill API keys
**~/.openclaw/agents/<agentId>/agent/auth-profiles.json**
## Environment Variables
### .env Files
OpenClaw loads env from (in order):
1. `.env` from current working directory (if present)
2. `~/.openclaw/.env` (global fallback)
### Inline Env Vars in Config
```json5
{
env: {
OPENROUTER_API_KEY: "sk-or-...",
vars: {
GROQ_API_KEY: "gsk-...",
},
},
}
```
### Shell Env Import
```json5
{
env: {
shellEnv: {
enabled: true,
timeoutMs: 15000,
},
},
}
```
Or `OPENCLAW_LOAD_SHELL_ENV=1`.
## Env Var Substitution
Use `${VAR_NAME}` in config values:
```json5
{
gateway: {
auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },
},
models: {
providers: {
custom: { apiKey: "${CUSTOM_API_KEY}" },
},
},
}
```
Rules:
- Only uppercase names matched: `[A-Z_][A-Z0-9_]*`
- Missing/empty vars throw error at load time
- Escape with `$${VAR}` for literal output
- Works inside `$include` files
- Inline: `"${BASE}/v1"` → `"https://api.example.com/v1"`
## Best Practices
1. **Never store plaintext API keys** in `openclaw.json` — use SecretRefs or env vars
2. **Run `openclaw secrets audit`** regularly to scan for plaintext leaks
3. **Use `openclaw secrets configure`** for interactive setup
4. **Prefer `source: "env"`** for simplicity, `source: "exec"` for vault integration
5. **File permissions**: `chmod 600 ~/.openclaw/secrets.json`
6. **Rotate secrets** immediately if you suspect compromise
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |