`velaclaw config`

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

--section <section>: repeatable guided-setup section filter when you run velaclaw config without a subcommand

Supported guided sections:

workspace
model
web
gateway
daemon
channels
plugins
skills
health

Examples

velaclaw config file
velaclaw config --section model
velaclaw config --section gateway --section daemon
velaclaw config schema
velaclaw config get browser.executablePath
velaclaw config set browser.executablePath "/usr/bin/google-chrome"
velaclaw config set agents.defaults.heartbeat.every "2h"
velaclaw config set agents.list[0].tools.exec.node "node-id-or-name"
velaclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
velaclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/velaclaw/secrets.json --provider-mode json
velaclaw config unset plugins.entries.brave.config.webSearch.apiKey
velaclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
velaclaw config validate
velaclaw config validate --json

`config schema`

Print the generated JSON schema for velaclaw.json to stdout as JSON. What it includes:

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

Related runtime RPC:

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.

velaclaw config schema

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

velaclaw config schema > velaclaw.schema.json

Paths

Paths use dot or bracket notation:

velaclaw config get agents.defaults.workspace
velaclaw config get agents.list[0].id

Use the agent list index to target a specific agent:

velaclaw config get agents.list
velaclaw 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.

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

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

`config set` modes

velaclaw config set supports four assignment styles:

Value mode: velaclaw config set <path> <value>
SecretRef builder mode:

velaclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN

Provider builder mode (secrets.providers.<alias> path only):

velaclaw config set secrets.providers.vault \
  --provider-source exec \
  --provider-command /usr/local/bin/velaclaw-vault \
  --provider-arg read \
  --provider-arg openai/api-key \
  --provider-timeout-ms 5000

Batch mode (--batch-json or --batch-file):

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

velaclaw config set --batch-file ./config-set.batch.json --dry-run

Policy note:

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.

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 remains supported for both SecretRefs and providers:

velaclaw config set channels.discord.token \
  '{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
  --strict-json

velaclaw config set secrets.providers.vaultfile \
  '{"source":"file","path":"/etc/velaclaw/secrets.json","mode":"json"}' \
  --strict-json

Provider Builder Flags

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

--provider-source <env|file|exec>
--provider-timeout-ms <ms> (file, exec)

Env provider (--provider-source env):

--provider-allowlist <ENV_VAR> (repeatable)

File provider (--provider-source file):

--provider-path <path> (required)
--provider-mode <singleValue|json>
--provider-max-bytes <bytes>

Exec provider (--provider-source exec):

--provider-command <path> (required)
--provider-arg <arg> (repeatable)
--provider-no-output-timeout-ms <ms>
--provider-max-output-bytes <bytes>
--provider-json-only
--provider-env <KEY=VALUE> (repeatable)
--provider-pass-env <ENV_VAR> (repeatable)
--provider-trusted-dir <path> (repeatable)
--provider-allow-insecure-path
--provider-allow-symlink-command

Hardened exec provider example:

velaclaw config set secrets.providers.vault \
  --provider-source exec \
  --provider-command /usr/local/bin/velaclaw-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 velaclaw.json.

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

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

velaclaw config set channels.discord.token \
  --ref-provider vault \
  --ref-source exec \
  --ref-id discord/token \
  --dry-run \
  --allow-exec

Dry-run behavior:

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 schema/resolvability failures when ok=false

JSON Output Shape

{
  ok: boolean,
  operations: number,
  configPath: string,
  inputModes: ["value" | "json" | "builder", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "schema" | "resolvability",
      message: string,
      ref?: string, // present for resolvability errors
    },
  ],
}

Success example:

{
  "ok": true,
  "operations": 1,
  "configPath": "~/.Zavianx/velaclaw-dev.json",
  "inputModes": ["builder"],
  "checks": {
    "schema": false,
    "resolvability": true,
    "resolvabilityComplete": true
  },
  "refsChecked": 1,
  "skippedExecRefs": 0
}

Failure example:

{
  "ok": false,
  "operations": 1,
  "configPath": "~/.Zavianx/velaclaw-dev.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"
    }
  ]
}

If dry-run fails:

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

Subcommands

config file: Print the active config file path (resolved from VELACLAW_CONFIG_PATH or default location).

Restart the gateway after edits.

Validate

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

velaclaw config validate
velaclaw config validate --json

CLI commands

RPC and API

Templates

Technical reference

Concept internals

Project

Release policy

config

`velaclaw config`

Examples

`config schema`

Paths

Values

`config set` modes

Provider Builder Flags

Dry run

JSON Output Shape

Subcommands

Validate

​velaclaw config

​Examples

​config schema

​Paths

​Values

​config set modes

​Provider Builder Flags

​Dry run

​JSON Output Shape

​Subcommands

​Validate

`velaclaw config`

Examples

`config schema`

Paths

Values

`config set` modes

Provider Builder Flags

Dry run

JSON Output Shape

Subcommands

Validate