Skip to content

LeoYeAI/agent-master-skills / skills/bengii-gemini-fix

openclaw

Flagged

Comprehensive 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.

FileKindSize
README.mdmarkdown7.5 KB
README_CN.mdmarkdown7.3 KB
SKILL.mdskill md18.7 KB
_meta.jsonconfig286 B
references/acp_agents.mdmarkdown12.6 KB
references/agent_runtime.mdmarkdown5.6 KB
references/architecture.mdmarkdown3.8 KB
references/automation.mdmarkdown5.8 KB
references/bonjour.mdmarkdown3.3 KB
references/browser.mdmarkdown8.5 KB
references/channel_routing.mdmarkdown4.0 KB
references/channel_troubleshooting.mdmarkdown11.6 KB
references/channels.mdmarkdown6.2 KB
references/clawhub.mdmarkdown3.6 KB
references/config_reference.mdmarkdown11.2 KB
references/diffs_firecrawl.mdmarkdown3.3 KB
references/elevated.mdmarkdown2.8 KB
references/exec.mdmarkdown6.5 KB
references/exec_approvals.mdmarkdown3.1 KB
references/gateway_internals.mdmarkdown7.7 KB
references/gateway_ops.mdmarkdown9.6 KB
references/heartbeat.mdmarkdown4.9 KB
references/hooks.mdmarkdown14.6 KB
references/install.mdmarkdown4.1 KB
references/llm_task.mdmarkdown2.6 KB
references/lobster.mdmarkdown7.8 KB
references/media.mdmarkdown4.2 KB
references/memory.mdmarkdown11.9 KB
references/model_failover.mdmarkdown3.1 KB
references/multi_agent.mdmarkdown4.4 KB
references/nodes.mdmarkdown8.8 KB
references/openprose.mdmarkdown2.6 KB
references/pairing.mdmarkdown3.1 KB
references/pdf_tool.mdmarkdown3.5 KB
references/platforms.mdmarkdown2.7 KB
references/plugins.mdmarkdown6.9 KB
references/polls.mdmarkdown2.2 KB
references/presence_discovery.mdmarkdown2.2 KB
references/providers.mdmarkdown6.0 KB
references/queue.mdmarkdown2.1 KB
references/remote_access.mdmarkdown4.7 KB
references/sandboxing.mdmarkdown5.6 KB
references/secrets.mdmarkdown5.4 KB
references/security.mdmarkdown24.5 KB
references/sessions.mdmarkdown8.9 KB
references/skills.mdmarkdown4.4 KB
references/slash_commands.mdmarkdown5.1 KB
references/streaming.mdmarkdown1.8 KB
references/subagents.mdmarkdown12.3 KB
references/thinking.mdmarkdown2.8 KB
references/tools.mdmarkdown13.3 KB
references/tui.mdmarkdown4.0 KB
references/voice.mdmarkdown2.7 KB
references/web_tools.mdmarkdown2.7 KB
references/web_ui.mdmarkdown4.5 KB

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
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall