Config

Config helpers for non-interactive edits in remoteclaw.json: get/set/patch/unset/file/schema/validate values by path and print the active config file. Run without a subcommand to open the configure wizard (same as remoteclaw configure).

When `REMOTECLAW_NIX_MODE=1`, RemoteClaw treats `remoteclaw.json` as immutable. Read-only commands such as `config get`, `config file`, `config schema`, and `config validate` still work, but config writers refuse. Agents should edit the Nix source for the install instead; for the first-party nix-remoteclaw distribution, use [nix-remoteclaw Quick Start](https://github.com/remoteclaw/nix-remoteclaw#quick-start) and set values under `programs.remoteclaw.config` or `instances..config`.

Root options

Repeatable guided-setup section filter when you run `remoteclaw config` without a subcommand.

Supported guided sections: workspace, model, web, gateway, daemon, channels, plugins, skills, health.

Examples

remoteclaw config file
remoteclaw config --section model
remoteclaw config --section gateway --section daemon
remoteclaw config schema
remoteclaw config get browser.executablePath
remoteclaw 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 --merge
remoteclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
remoteclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/remoteclaw/secrets.json --provider-mode json
remoteclaw config patch --file ./remoteclaw.patch.json5 --dry-run
remoteclaw config unset plugins.entries.brave.config.webSearch.apiKey
remoteclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
remoteclaw config validate
remoteclaw config validate --json

config schema

Print the generated JSON schema for remoteclaw.json to stdout as JSON.

- The current root config schema, plus a root `$schema` string field for editor tooling. - Field `title` and `description` docs metadata used by the Control UI. - Nested object, wildcard (`*`), and array-item (`[]`) nodes inherit the same `title` / `description` metadata when matching field documentation exists. - `anyOf` / `oneOf` / `allOf` branches inherit the same docs metadata too when matching field documentation exists. - Best-effort live plugin + channel schema metadata when runtime manifests can be loaded. - A clean fallback schema even when the current config is invalid. `config.schema.lookup` returns one normalized config path with a shallow schema node (`title`, `description`, `type`, `enum`, `const`, common bounds), matched UI hint metadata, and immediate child summaries. Use it for path-scoped drill-down in Control UI or custom clients.

remoteclaw config schema

Pipe it into a file when you want to inspect or validate it with other tools:

remoteclaw config schema > remoteclaw.schema.json

Paths

Paths use dot or bracket notation. Quote bracket-notation paths in shell examples so shells such as zsh do not expand [0] as a glob before RemoteClaw receives the path:

remoteclaw config get agents.defaults.workspace
remoteclaw config get 'agents.list[0].id'

Use the agent list index to target a specific agent:

remoteclaw config get agents.list
remoteclaw config set 'agents.list[1].tools.exec.node' "node-id-or-name"

Values

Values are parsed as JSON5 when possible; otherwise they are treated as strings. Use --strict-json to require JSON5 parsing. --json remains supported as a legacy alias.

remoteclaw config set agents.defaults.heartbeat.every "0m"
remoteclaw config set gateway.port 19001 --strict-json
remoteclaw config set channels.whatsapp.groups '["*"]' --strict-json

config get <path> --json prints the raw value as JSON instead of terminal-formatted text.

Object assignment replaces the target path by default. Protected map/list paths that commonly hold user-added entries, such as `agents.defaults.models`, `models.providers`, `models.providers..models`, `plugins.entries`, and `auth.profiles`, refuse replacements that would remove existing entries unless you pass `--replace`.

Use --merge when adding entries to those maps:

remoteclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
remoteclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge

Use --replace only when you intentionally want the provided value to become the complete target value.

config set modes

remoteclaw config set supports four assignment styles:

```bash remoteclaw config set ``` ```bash remoteclaw config set channels.discord.token \ --ref-provider default \ --ref-source env \ --ref-id DISCORD_BOT_TOKEN ``` Provider builder mode targets `secrets.providers.` paths only:

```bash
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-timeout-ms 5000
```

```bash remoteclaw config set --batch-json '[ { "path": "secrets.providers.default", "provider": { "source": "env" } }, { "path": "channels.discord.token", "ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" } } ]' ```

```bash
remoteclaw config set --batch-file ./config-set.batch.json --dry-run
```

SecretRef assignments are rejected on unsupported runtime-mutable surfaces (for example `hooks.token`, `commands.ownerDisplaySecret`, Discord thread-binding webhook tokens, and WhatsApp creds JSON). See [SecretRef Credential Surface](/reference/secretref-credential-surface).

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.

config patch

Use config patch when you want to paste or pipe a config-shaped patch instead of running many path-based config set commands. The input is a JSON5 object. Objects merge recursively, arrays and scalar values replace the target value, and null deletes the target path.

remoteclaw config patch --file ./remoteclaw.patch.json5 --dry-run
remoteclaw config patch --file ./remoteclaw.patch.json5

You can also pipe a patch over stdin, which is useful for remote setup scripts:

ssh remoteclaw-host 'remoteclaw config patch --stdin --dry-run' < ./remoteclaw.patch.json5
ssh remoteclaw-host 'remoteclaw config patch --stdin' < ./remoteclaw.patch.json5

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

JSON path/value mode remains supported for both SecretRefs and providers:

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-json

Provider builder flags

Provider builder targets must use secrets.providers.<alias> as the path.

- `--provider-source ` - `--provider-timeout-ms ` (`file`, `exec`) - `--provider-allowlist ` (repeatable) - `--provider-path ` (required) - `--provider-mode ` - `--provider-max-bytes ` - `--provider-allow-insecure-path` - `--provider-command ` (required) - `--provider-arg ` (repeatable) - `--provider-no-output-timeout-ms ` - `--provider-max-output-bytes ` - `--provider-json-only` - `--provider-env ` (repeatable) - `--provider-pass-env ` (repeatable) - `--provider-trusted-dir ` (repeatable) - `--provider-allow-insecure-path` - `--provider-allow-symlink-command`

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 5000

Dry run

Use --dry-run to validate changes without writing remoteclaw.json.

remoteclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run

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-exec

- Builder mode: runs SecretRef resolvability checks for changed refs/providers. - JSON mode (`--strict-json`, `--json`, or batch mode): runs schema validation plus SecretRef resolvability checks. - Policy validation also runs for known unsupported SecretRef target surfaces. - Policy checks evaluate the full post-change config, so parent-object writes (for example setting `hooks` as an object) cannot bypass unsupported-surface validation. - Exec SecretRef checks are skipped by default during dry-run to avoid command side effects. - Use `--allow-exec` with `--dry-run` to opt in to exec SecretRef checks (this may execute provider commands). - `--allow-exec` is dry-run only and errors if used without `--dry-run`. `--dry-run --json` prints a machine-readable report:

- `ok`: whether dry-run passed
- `operations`: number of assignments evaluated
- `checks`: whether schema/resolvability checks ran
- `checks.resolvabilityComplete`: whether resolvability checks ran to completion (false when exec refs are skipped)
- `refsChecked`: number of refs actually resolved during dry-run
- `skippedExecRefs`: number of exec refs skipped because `--allow-exec` was not set
- `errors`: structured missing-path, schema, or resolvability failures when `ok=false`

JSON 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
    },
  ],
}

```json { "ok": true, "operations": 1, "configPath": "~/.remoteclaw/remoteclaw.json", "inputModes": ["builder"], "checks": { "schema": false, "resolvability": true, "resolvabilityComplete": true }, "refsChecked": 1, "skippedExecRefs": 0 } ``` ```json { "ok": false, "operations": 1, "configPath": "~/.remoteclaw/remoteclaw.json", "inputModes": ["builder"], "checks": { "schema": false, "resolvability": true, "resolvabilityComplete": true }, "refsChecked": 1, "skippedExecRefs": 0, "errors": [ { "kind": "resolvability", "message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.", "ref": "env:default:MISSING_TEST_SECRET" } ] } ``` - `config schema validation failed`: your post-change config shape is invalid; fix path/value or provider/ref object shape. - `Config policy validation failed: unsupported SecretRef usage`: move that credential back to plaintext/string input and keep SecretRefs on supported surfaces only. - `SecretRef assignment(s) could not be resolved`: referenced provider/ref currently cannot resolve (missing env var, invalid file pointer, exec provider failure, or provider/source mismatch). - `Dry run note: skipped exec SecretRef resolvability check(s)`: dry-run skipped exec refs; rerun with `--allow-exec` if you need exec resolvability validation. - For batch mode, fix failing entries and rerun `--dry-run` before writing.

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

The active config path must be a regular file. Symlinked `remoteclaw.json` layouts are unsupported for writes; use `REMOTECLAW_CONFIG_PATH` to point directly at the real file instead.

Prefer CLI writes for small edits:

remoteclaw config set gateway.reload.mode hybrid --dry-run
remoteclaw config set gateway.reload.mode hybrid
remoteclaw config validate

If 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 | head
remoteclaw config validate

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

Subcommands

• config file: Print the active config file path (resolved from REMOTECLAW_CONFIG_PATH or default location). The path should name a regular file, not a symlink.

Restart the gateway after edits.

Validate

Validate the current config against the active schema without starting the gateway.

remoteclaw config validate
remoteclaw config validate --json

After remoteclaw config validate is passing, you can 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:

If validation is already failing, start with `remoteclaw configure` or `remoteclaw doctor --fix`. `remoteclaw chat` does not bypass the invalid-config guard.

remoteclaw chat

Then inside the TUI:

!remoteclaw config file
!remoteclaw docs gateway auth token secretref
!remoteclaw config validate
!remoteclaw doctor

Typical repair loop:

Ask the agent to compare your current config with the relevant docs page and suggest the smallest fix. Apply targeted edits with `remoteclaw config set` or `remoteclaw configure`. Rerun `remoteclaw config validate` after each change. If validation passes but the runtime is still unhealthy, run `remoteclaw doctor` or `remoteclaw doctor --fix` for migration and repair help.

Related

• CLI reference
• Configuration