Pulse
22d9f5b21d
Novas skills instaladas: - openclaw-agent-browser v1.0.0 CLI Chromium — navegação, login, screenshots, state - skill-security-audit v1.0.0 SAST scanning, prompt injection, secrets audit - sql-toolkit v1.0.0 PostgreSQL/MySQL/SQLite — schema, query, otimização - file v1.0.0 Organização de arquivos por contexto - file-summary v1.0.0 Extração e resumo de PDFs, Word, Excel Workspace expandido: - TOOLS.md: +Browser automation, Security audit, SQL, File management - AGENTS.md: +Linux Analyst section (comandos, logs, rede, scripts) + Full-stack strategy - MEMORY.md: 16 skills indexadas, stack map, comandos Linux ref - SESSION-STATE.md: atualizado com contexto completo - lock.json: sincronizado com 16 skills instaladas
124 lines
4.6 KiB
Markdown
124 lines
4.6 KiB
Markdown
---
|
|
name: openclaw-config
|
|
description: Edit and validate OpenClaw Gateway config (openclaw.json / JSON5). Use when adding/changing config keys (gateway.*, agents.*, models.*, channels.*, tools.*, skills.*, plugins.*, $include) or diagnosing openclaw doctor/config validation errors, to avoid schema mismatches that prevent the Gateway from starting or weaken security policies.
|
|
---
|
|
|
|
# OpenClaw Config
|
|
|
|
## Overview
|
|
|
|
Safely edit `~/.openclaw/openclaw.json` (or the path set by `OPENCLAW_CONFIG_PATH`) using a schema-first workflow. Validate before and after changes to avoid invalid keys/types that can break startup or change security behavior.
|
|
|
|
## Workflow (Safe Edit)
|
|
|
|
1. **Identify the active config path**
|
|
|
|
- Precedence: `OPENCLAW_CONFIG_PATH` > `OPENCLAW_STATE_DIR/openclaw.json` > `~/.openclaw/openclaw.json`
|
|
- The config file is **JSON5** (comments + trailing commas allowed).
|
|
|
|
2. **Get an authoritative schema (do not guess keys)**
|
|
|
|
- If the Gateway is running: use `openclaw gateway call config.schema --params '{}'` to fetch a JSON Schema matching the running version.
|
|
- Otherwise: use `openclaw/openclaw` source-of-truth, primarily:
|
|
- `src/config/zod-schema.ts` (`OpenClawSchema` root keys like `gateway`/`skills`/`plugins`)
|
|
- `src/config/zod-schema.*.ts` (submodules: channels/providers/models/agents/tools)
|
|
- `docs/gateway/configuration.md` (repo docs + examples)
|
|
|
|
3. **Apply changes with the smallest safe surface**
|
|
|
|
- Prefer small edits: `openclaw config get|set|unset` (dot path or bracket notation).
|
|
- If the Gateway is online and you want "write + validate + restart" in one step: use RPC `config.patch` (merge patch) or `config.apply` (replaces the entire config; use carefully).
|
|
- For complex setups, split config with `$include` (see below).
|
|
|
|
4. **Validate strictly**
|
|
|
|
- Run `openclaw doctor`, then fix issues using the reported `path` + `message`.
|
|
- Do not run `openclaw doctor --fix/--yes` without explicit user consent (it writes to config/state files).
|
|
|
|
## Guardrails (Avoid Schema Bugs)
|
|
|
|
- **Most objects are strict** (`.strict()`): unknown keys usually fail validation and the Gateway will refuse to start.
|
|
- `channels` is `.passthrough()`: extension channels (matrix/zalo/nostr, etc.) can add custom keys, but most provider configs remain strict.
|
|
- `env` is `.catchall(z.string())`: you can put string env vars directly under `env`, and you can also use `env.vars`.
|
|
- **Secrets**: prefer environment variables/credential files. Avoid committing long-lived tokens/API keys into `openclaw.json`.
|
|
|
|
## $include (Modular Config)
|
|
|
|
`$include` is resolved before schema validation and lets you split config across JSON5 files:
|
|
|
|
- Supports `"$include": "./base.json5"` or `"$include": ["./a.json5", "./b.json5"]`
|
|
- Relative paths are resolved against the directory of the current config file.
|
|
- Deep-merge rules (per implementation):
|
|
- objects: merge recursively
|
|
- arrays: **concatenate** (not replace)
|
|
- primitives: later value wins
|
|
- If sibling keys exist alongside `$include`, sibling keys override included values.
|
|
- Limits: max depth 10; circular includes are detected and rejected.
|
|
|
|
## Common Recipes (Examples)
|
|
|
|
1. Set default workspace
|
|
|
|
```bash
|
|
openclaw config set agents.defaults.workspace '"~/.openclaw/workspace"' --json
|
|
openclaw doctor
|
|
```
|
|
|
|
2. Change Gateway port
|
|
|
|
```bash
|
|
openclaw config set gateway.port 18789 --json
|
|
openclaw doctor
|
|
```
|
|
|
|
3. Split config (example)
|
|
|
|
```json5
|
|
// ~/.openclaw/openclaw.json
|
|
{
|
|
"$include": ["./gateway.json5", "./channels/telegram.json5"],
|
|
}
|
|
```
|
|
|
|
4. Telegram open DMs (must explicitly allow senders)
|
|
|
|
> Schema constraint: when `dmPolicy="open"`, `allowFrom` must include `"*"`.
|
|
|
|
```bash
|
|
openclaw config set channels.telegram.dmPolicy '"open"' --json
|
|
openclaw config set channels.telegram.allowFrom '["*"]' --json
|
|
openclaw doctor
|
|
```
|
|
|
|
5. Discord token (config or env fallback)
|
|
|
|
```bash
|
|
# Option A: write to config
|
|
openclaw config set channels.discord.token '"YOUR_DISCORD_BOT_TOKEN"' --json
|
|
|
|
# Option B: env var fallback (still recommend a channels.discord section exists)
|
|
# export DISCORD_BOT_TOKEN="..."
|
|
|
|
openclaw doctor
|
|
```
|
|
|
|
6. Enable web_search (Brave / Perplexity)
|
|
|
|
```bash
|
|
openclaw config set tools.web.search.enabled true --json
|
|
openclaw config set tools.web.search.provider '"brave"' --json
|
|
|
|
# Recommended: provide the key via env var (or write tools.web.search.apiKey)
|
|
# export BRAVE_API_KEY="..."
|
|
|
|
openclaw doctor
|
|
```
|
|
|
|
## Resources
|
|
|
|
Load these when you need a field index or source locations:
|
|
|
|
- `references/openclaw-config-fields.md` (root key index + key field lists with sources)
|
|
- `references/schema-sources.md` (how to locate schema + constraints in openclaw repo)
|
|
- `scripts/openclaw-config-check.sh` (print config path + run doctor)
|