Config
Non-interactive helpers for remoteclaw.json: get/set/patch/unset a value by path, print the schema, validate, or print the active file path. Run remoteclaw config with no subcommand to open the same guided wizard as remoteclaw configure.
Root options
Guided sections: workspace, model, web, gateway, daemon, channels, plugins, skills, health.
Examples
remoteclaw config fileremoteclaw config --section modelremoteclaw config --section gateway --section daemonremoteclaw config schemaremoteclaw config get browser.executablePathremoteclaw config set browser.executablePath "/usr/bin/google-chrome"remoteclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"remoteclaw config set agents.defaults.heartbeat.every "2h"remoteclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name"remoteclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --mergeremoteclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKENremoteclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/remoteclaw/secrets.json --provider-mode jsonremoteclaw config patch --file ./remoteclaw.patch.json5 --dry-runremoteclaw config unset plugins.entries.brave.config.webSearch.apiKeyremoteclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-runremoteclaw config validateremoteclaw config validate --jsonPaths
Dot or bracket notation. Quote bracket paths in shell examples so zsh does not glob-expand [0]:
remoteclaw config get agents.defaults.workspaceremoteclaw config get 'agents.list[0].id'remoteclaw config get agents.listremoteclaw config set 'agents.list[1].tools.exec.node' "node-id-or-name"config get
Reads a value from the redacted config snapshot (secrets never print). --json prints the raw value as JSON; otherwise strings/numbers/booleans print bare and objects/arrays print as formatted JSON.
remoteclaw config get browser.executablePathremoteclaw config get agents.defaults.model --jsonconfig file
Prints the active config file path, resolved from REMOTECLAW_CONFIG_PATH or the default location. The path names a regular file, not a symlink; see Write safety.
config schema
Prints the generated JSON schema for remoteclaw.json to stdout.
remoteclaw config schemaremoteclaw config schema > remoteclaw.schema.jsonconfig validate
Validates the current config against the active schema without starting the gateway.
remoteclaw config validateremoteclaw config validate --jsonValues
Values parse as JSON5 when possible; otherwise they are treated as raw strings. Use --strict-json to require standard JSON with no string fallback (JSON5-only syntax such as comments, trailing commas, or unquoted keys is then rejected). --json is a legacy alias for --strict-json on config set.
remoteclaw config set agents.defaults.heartbeat.every "0m"remoteclaw config set gateway.port 19001 --strict-jsonremoteclaw config set channels.whatsapp.groups '["*"]' --strict-jsonconfig get <path> --json prints the raw value as JSON instead of terminal-formatted text.
Use --merge when adding entries to those maps:
remoteclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --mergeremoteclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --mergeUse --replace only when the provided value should intentionally become the complete target value.
config set modes
```bashremoteclaw config set secrets.providers.vault \ --provider-source exec \ --provider-command /usr/local/bin/remoteclaw-vault \ --provider-arg read \ --provider-arg openai/api-key \ --provider-timeout-ms 5000``````bashremoteclaw config set --batch-file ./config-set.batch.json --dry-run```Batch parsing always uses the batch payload (--batch-json/--batch-file) as the source of truth; --strict-json / --json do not change batch parsing behavior.
JSON path/value mode also works for SecretRefs and providers directly:
remoteclaw config set channels.discord.token \ '{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \ --strict-json
remoteclaw config set secrets.providers.vaultfile \ '{"source":"file","path":"/etc/remoteclaw/secrets.json","mode":"json"}' \ --strict-jsonProvider builder flags
Provider builder targets must use secrets.providers.<alias> as the path.
Hardened exec provider example:
remoteclaw config set secrets.providers.vault \ --provider-source exec \ --provider-command /usr/local/bin/remoteclaw-vault \ --provider-arg read \ --provider-arg openai/api-key \ --provider-json-only \ --provider-pass-env VAULT_TOKEN \ --provider-trusted-dir /usr/local/bin \ --provider-timeout-ms 5000config patch
Paste or pipe a config-shaped JSON5 patch instead of running many path-based config set commands. Objects merge recursively; arrays and scalar values replace the target; null deletes the target path.
remoteclaw config patch --file ./remoteclaw.patch.json5 --dry-runremoteclaw config patch --file ./remoteclaw.patch.json5Pipe a patch over stdin for remote setup scripts:
ssh user@gateway-host 'remoteclaw config patch --stdin --dry-run' < ./remoteclaw.patch.json5ssh user@gateway-host 'remoteclaw config patch --stdin' < ./remoteclaw.patch.json5Example patch:
{ channels: { slack: { enabled: true, mode: "socket", botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" }, appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" }, groupPolicy: "open", requireMention: false, }, discord: { enabled: true, token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" }, dmPolicy: "disabled", dm: { enabled: false }, groupPolicy: "allowlist", }, }, agents: { defaults: { model: { primary: "openai/gpt-5.5" }, models: { "openai/gpt-5.5": { params: { fastMode: true } }, }, }, },}Use --replace-path <path> when one object or array must become exactly the provided value instead of being recursively patched:
remoteclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'--dry-run runs schema and SecretRef resolvability checks without writing. Exec-backed SecretRefs are skipped by default during dry-run; add --allow-exec when you intentionally want dry-run to execute provider commands.
Dry run
--dry-run validates changes without writing remoteclaw.json. Available on config set, config patch, and config unset.
remoteclaw config set channels.discord.token \ --ref-provider default \ --ref-source env \ --ref-id DISCORD_BOT_TOKEN \ --dry-run \ --json
remoteclaw config set channels.discord.token \ --ref-provider vault \ --ref-source exec \ --ref-id discord/token \ --dry-run \ --allow-execJSON output shape
{ ok: boolean, operations: number, configPath: string, inputModes: ["value" | "json" | "builder" | "unset", ...], checks: { schema: boolean, resolvability: boolean, resolvabilityComplete: boolean, }, refsChecked: number, skippedExecRefs: number, errors?: [ { kind: "missing-path" | "schema" | "resolvability", message: string, ref?: string, // present for resolvability errors }, ],}Applying changes
After every successful config set / config patch / config unset, the CLI prints one of three hints so you know whether the gateway needs a restart:
| Hint | Meaning |
|---|---|
Restart the gateway to apply. | The changed path needs a full restart. |
Change will apply without restarting the gateway. | Hot reload picks it up automatically. |
No gateway restart needed. | Nothing runtime-relevant changed. |
Writes to plugins.entries (or any subpath) always require a restart, since the CLI cannot prove every plugin’s reload metadata is loaded.
Write safety
remoteclaw config set and other RemoteClaw-owned config writers validate the full post-change config before committing it to disk. If the new payload fails schema validation or looks like a destructive clobber, the active config is left alone and the rejected payload is saved beside it as remoteclaw.json.rejected.*.
Prefer CLI writes for small edits:
remoteclaw config set gateway.reload.mode hybrid --dry-runremoteclaw config set gateway.reload.mode hybridremoteclaw config validateIf a write is rejected, inspect the saved payload and fix the full config shape:
CONFIG="$(remoteclaw config file)"ls -lt "$CONFIG".rejected.* 2>/dev/null | headremoteclaw config validateDirect editor writes are still allowed, but the running Gateway treats them as untrusted until they validate. Invalid direct edits fail startup or are skipped by hot reload; Gateway does not rewrite remoteclaw.json. Run remoteclaw doctor --fix to repair prefixed/clobbered config or restore the last-known-good copy. See Gateway troubleshooting.
Whole-file recovery is reserved for doctor repair. Plugin schema changes or minHostVersion skew stay loud instead of rolling back unrelated user settings such as models, providers, auth profiles, channels, gateway exposure, tools, memory, browser, or cron config.
Repair loop
After remoteclaw config validate passes, use the local TUI to have an embedded agent compare the active config against the docs while you validate each change from the same terminal:
remoteclaw chatInside the TUI, a leading ! runs a literal local shell command (after a one-time per-session confirmation prompt):
!remoteclaw config file!remoteclaw docs gateway auth token secretref!remoteclaw config validate!remoteclaw doctor