Configuration
superclaw is configured via a superclaw.json file and CLI flags. All fields are optional — sensible defaults apply when any field is omitted.
Configuration precedence
Settings are resolved in this order (later sources win):
A superclaw.json in the current working directory is loaded automatically. Use -config /path/to/file.json to specify a different path.
superclaw.json field reference
| Field | Type | Default | Description |
|---|---|---|---|
| model | string | claude-opus-4-5 | The Anthropic model ID to use. Any model available via the Messages API is accepted. |
| max_steps | integer | 20 | Maximum number of tool-call rounds. The agent stops (with an error) if this limit is reached before the task is complete. |
| max_tokens | integer | 4096 | Maximum tokens in each model response. Does not control total run cost — only per-call output length. |
| timeout_seconds | integer | 120 | Wall-clock timeout for the entire run, in seconds. Includes model latency and tool execution time. |
| work_dir | string | "" (cwd) | Working directory for file operations and run_bash. Defaults to the current working directory at launch. |
| max_fetch_calls | integer | 5 | Maximum number of fetch_url and web_search calls per run. Prevents runaway crawling. |
| tools | []string | all tools | Explicit allowlist of tool names. If omitted, all 7 tools are available. Use this to restrict agent capabilities. |
| skills | []string | [] | List of skills to inject into the system prompt. Valid values: summarize, research, extract, coding, github. |
| system_prompt | string | "" | Additional system prompt text appended after the skill instructions. Use for project-specific context or constraints. |
CLI flag reference
| Flag | Overrides | Description |
|---|---|---|
| -model <id> | model | Override the model ID |
| -max-steps <n> | max_steps | Override the step limit |
| -max-tokens <n> | max_tokens | Override output token limit |
| -timeout <n> | timeout_seconds | Override run timeout (seconds) |
| -work-dir <path> | work_dir | Override the working directory |
| -max-fetch <n> | max_fetch_calls | Override the fetch call limit |
| -skills <a,b> | skills | Comma-separated skill names |
| -config <path> | — | Path to a superclaw.json file (default: ./superclaw.json) |
| -dry-run | — | Print resolved config and task plan; do not execute |
| -verbose | — | Print full tool input/output for each step |
| -version | — | Print version and exit |
Full default config
This is equivalent to running superclaw with no config file — all defaults made explicit:
1{2 "model": "claude-opus-4-5",3 "max_steps": 20,4 "max_tokens": 4096,5 "timeout_seconds": 120,6 "work_dir": "/workspace",7 "max_fetch_calls": 5,8 "tools": [9 "fetch_url",10 "web_search",11 "read_file",12 "write_file",13 "patch_file",14 "list_files",15 "run_bash"16 ],17 "skills": [],18 "system_prompt": ""19}Restricted example
A minimal config for a coding assistant with a restricted tool set and a shorter timeout:
1{2 "model": "claude-haiku-4-5",3 "max_steps": 8,4 "max_tokens": 2048,5 "timeout_seconds": 45,6 "tools": ["read_file", "write_file", "list_files"],7 "skills": ["coding"],8 "system_prompt": "You are working in a Python project. Prefer idiomatic Python 3.12."9}Config validation
superclaw validates the config at startup and exits with a descriptive error if something is wrong. Common validation errors:
Unknown tool name in tools array
invalid tool "scrape_page": not in allowlist. Valid tools: fetch_url, web_search, read_file, write_file, patch_file, list_files, run_bashUnknown skill name in skills array
invalid skill "summarise": unknown skill. Valid skills: summarize, research, extract, coding, githubmax_steps out of range
max_steps must be between 1 and 100, got 0timeout_seconds out of range
timeout_seconds must be between 5 and 3600, got 2