# `.rcs-config.json` model/env routing reference

This page documents the `.rcs-config.json` keys that current RCS code recognizes, with extra detail for **model and environment routing**. Feature-owned settings such as notifications and OpenClaw remain documented near those features, but their supported key shapes are summarized here so this page can act as a safe schema map.

This is a runtime/config reference. Keys such as `team`, `autopilot`, and `forge` below refer to runtime execution-mode identifiers, not the primary public creator workflow language. Public onboarding should still lead with `$brief`, `$blueprint`, `$forge`, `$crew`, and `$autoforge`.

Do not add or edit keys unless your installed RCS version recognizes them. Unknown keys are not a stable extension point, and malformed JSON or wrong-shaped sections may be ignored or may fail closed for the feature reading them.

## Where the file is read

Most `.rcs-config.json` readers resolve through the active Codex home:

| Setup shape | Config file | Notes |
| --- | --- | --- |
| User scope | `${CODEX_HOME:-~/.codex}/.rcs-config.json` | Default setup shape. `CODEX_HOME` wins when set. |
| Project scope | `./.codex/.rcs-config.json` | Used by RCS launch paths when `./.rcs/setup-scope.json` says `project` and `CODEX_HOME` is not already set. |

Project-scoped setup also writes `./.codex/config.toml`, `./.codex/hooks.json`, and project-local skills/prompts/agents. User-scoped setup writes the corresponding files under `${CODEX_HOME:-~/.codex}`.

The wiki lifecycle reader is a project-root exception because it runs from hook payload `cwd`: it checks `<root>/.rcs-config.json` first, then `${CODEX_HOME:-~/.codex}/.rcs-config.json`, and falls back to built-in wiki defaults if neither file has a valid `wiki` object. The project-scope Codex-home file `./.codex/.rcs-config.json` still applies when `CODEX_HOME` resolves to `./.codex`; it is not an extra wiki-only lookup path.

`rcs setup --scope project` persists the project-scope choice in `./.rcs/setup-scope.json`; `rcs doctor` prints the resolved setup scope and the Codex home/config paths it is checking.

## Supported top-level keys

Current code recognizes these top-level `.rcs-config.json` keys:

| Top-level key | Supported shape | Primary use |
| --- | --- | --- |
| `env` | Object of non-empty string values | Fallback environment values for model routing and helper launch paths. Model-related supported keys are listed below. |
| `models` | Object of non-empty string values | Mode defaults and low-complexity model aliases. Supported model-routing keys are listed below. |
| `providers` | Object | Provider profiles for model/API-agnostic routing (`base_url`, `api_format`, `env_key`, `capabilities`, `label`). |
| `routing` | Object | Default provider, mode-specific provider mapping, fallback provider chains, and hot-swap/failover flags. |
| `notifications` | Object | Notification transports, profiles, templates, cooldowns, replies, and OpenClaw/custom aliases. See the notification summary below and the OpenClaw guide for full examples. |
| `stopHookCallbacks` | Legacy object | Backward-compatible legacy session-end notification config for `telegram` and `discord`; prefer `notifications`. |
| `promptRouting` | `{ "triage": { "enabled": boolean } }` | Enables/disables advisory triage prompt routing. Missing key defaults to enabled; malformed shape fails closed to disabled. |
| `autoNudge` | Object | Managed-tmux stall nudge settings. Supported keys: `enabled`, `patterns`, `response`, `delaySec`, `stallMs`, `ttlMs`, and legacy `cooldownMs`. |
| `wiki` | Object | Project wiki lifecycle settings. Supported keys: `enabled`, `autoCapture`, `maxContextLines`, `staleDays`, `maxPageSize`, `feedProjectMemoryOnStart`. |

### Notification-owned keys

`notifications` supports the following current shapes:

- Global fields: `enabled`, `verbosity` (`verbose`, `agent`, `session`, or `minimal`), `defaultProfile`, `profiles`, `events`, `hookTemplates`, `reply`, `dispatchCooldownSeconds`, and `idleCooldownSeconds`.
- Platform fields: `discord`, `discord-bot`, `telegram`, `slack`, `webhook`.
- OpenClaw/custom transport fields: `openclaw`, `custom_webhook_command`, and `custom_cli_command`.
- Event keys under `events`: `session-start`, `session-stop`, `session-end`, `session-idle`, and `ask-user-question`. Each event can set `enabled`, `messageTemplate`, and platform overrides.
- `hookTemplates` supports `version`, `enabled`, `events`, and `defaultTemplate`; per-event template config supports `enabled`, `template`, and platform template overrides.
- `reply` supports `enabled`, `authorizedDiscordUserIds`, `pollIntervalMs`, `rateLimitPerMinute`, `maxMessageLength`, and `includePrefix`.
- `notifications.openclaw` supports `enabled`, `gateways`, and `hooks`. Gateway entries are HTTP (`type`, `url`, `headers`, `method`, `timeout`) or command (`type`, `command`, `timeout`). Hook entries use `gateway`, `instruction`, and `enabled`.

Use [`docs/openclaw-integration.md`](../openclaw-integration.md) for full notification/OpenClaw examples. Keep credentials in environment variables where possible.

## Supported model/env keys

The model-routing reader supports two top-level objects: `env` and `models`.

```json
{
  "env": {
    "RCS_DEFAULT_FRONTIER_MODEL": "gpt-5.5",
    "RCS_DEFAULT_STANDARD_MODEL": "gpt-5.4-mini",
    "RCS_DEFAULT_SPARK_MODEL": "gpt-5.3-codex-spark"
  },
  "models": {
    "default": "gpt-5.5",
    "team": "gpt-5.5",
    "team_low_complexity": "gpt-5.3-codex-spark"
  }
}
```

### `env`

`env` provides fallback environment values when the real shell environment did not set them. Shell environment variables still win.

Supported model-related keys:

| Key | Purpose |
| --- | --- |
| `RCS_DEFAULT_FRONTIER_MODEL` | Main/frontier default used by leaders and frontier-class roles when no stronger config wins. |
| `RCS_DEFAULT_STANDARD_MODEL` | Optional standard-lane override. If omitted, standard agents inherit the main/frontier default. |
| `RCS_DEFAULT_SPARK_MODEL` | Spark/fast-lane default for low-cost exploration and low-complexity workers. |
| `RCS_SPARK_MODEL` | Legacy spark fallback; prefer `RCS_DEFAULT_SPARK_MODEL` for new config. |
| `RCS_TEAM_CHILD_MODEL` | Default child model for specific team-child paths that read this setting directly. |

`readConfiguredEnvOverrides()` also passes through other non-empty string values from `env` for launch helpers such as `rcs explore` and `rcs sparkshell`. Treat those as advanced environment overrides, not a schema for per-role model routing.

### `models`

`models` maps mode names to explicit model overrides. Values must be non-empty strings.

Supported model-routing keys:

| Key shape | Purpose |
| --- | --- |
| `default` | Fallback for `getModelForMode(mode)` when the requested mode has no explicit key. |
| Any mode key, for example `team`, `autopilot`, `forge` | Explicit model for that mode when code calls `getModelForMode("mode")`. |
| `team_low_complexity` | Low-complexity team/spark model override. |
| `team-low-complexity` | Alias for `team_low_complexity`. |
| `teamLowComplexity` | Alias for `team_low_complexity`. |

Do not invent per-role maps such as `models.executor`, `models.architect`, or `models.roles` unless your installed version documents that exact key. Current role routing is based on agent definitions and model class, not arbitrary per-role JSON maps.

## Effective model precedence

### Main/frontier default

The main default resolves in this order:

1. Shell `RCS_DEFAULT_FRONTIER_MODEL`
2. `.rcs-config.json` `env.RCS_DEFAULT_FRONTIER_MODEL`
3. Active Codex `config.toml` root `model`
4. Built-in default: `gpt-5.5`

### Mode-specific model lookup

When code asks for `getModelForMode(mode)`, the mode model resolves in this order:

1. `.rcs-config.json` `models[mode]`
2. `.rcs-config.json` `models.default`
3. Main/frontier default above

Example: with `models.team = "gpt-5.5"` and `models.default = "gpt-5.4-mini"`, `team` uses `gpt-5.5`; a mode without its own key uses `gpt-5.4-mini`.

### Standard-lane agents

Standard-lane agents resolve in this order:

1. Shell `RCS_DEFAULT_STANDARD_MODEL`
2. `.rcs-config.json` `env.RCS_DEFAULT_STANDARD_MODEL`
3. Main/frontier default

This means standard agents inherit the leader/frontier model unless you opt into a standard-lane override.

### Spark/fast-lane agents

Spark/fast defaults resolve in this order:

1. Shell `RCS_DEFAULT_SPARK_MODEL`
2. Shell legacy `RCS_SPARK_MODEL`
3. `.rcs-config.json` `env.RCS_DEFAULT_SPARK_MODEL`
4. `.rcs-config.json` legacy `env.RCS_SPARK_MODEL`
5. `.rcs-config.json` `models.team_low_complexity`, `models.team-low-complexity`, or `models.teamLowComplexity`
6. Built-in default: `gpt-5.3-codex-spark`

For team low-complexity helpers, the exact order depends on the call path: `getSparkDefaultModel()` checks spark env/config values before low-complexity aliases, while `getTeamLowComplexityModel()` checks low-complexity aliases before falling back to the spark default.

## Role/category routing examples

Native agent TOML generation and team model-contract logic use agent definitions with `modelClass` and `reasoningEffort` metadata. Native-agent generation has one important frontier-lane precedence detail: for frontier roles and the `executor` special case, it reads the active Codex `config.toml` root `model` first, then falls back to `getMainDefaultModel()` if that root model is absent. Because `getMainDefaultModel()` is only the fallback in this path, `.rcs-config.json` `env.RCS_DEFAULT_FRONTIER_MODEL` does not override an explicit `config.toml` root `model` for generated native-agent TOML.

Examples:

| Role/category | Examples | Model class behavior |
| --- | --- | --- |
| Frontier orchestration | `planner`, `architect`, `critic`, `code-reviewer`, `security-reviewer`, `team-executor`, `vision` | Native-agent generation uses active `config.toml` root `model` first, then the main/frontier default fallback. |
| Standard worker/review | `debugger`, `code-reviewer`, `dependency-expert`, `writer`, `researcher`, `security-reviewer` | Uses the standard-lane default, which inherits main/frontier unless `RCS_DEFAULT_STANDARD_MODEL` is set. |
| Fast/low-complexity | `explore`, `writer` | Uses the spark/low-complexity default. |
| Executor special case | `executor` | Native-agent generation uses active `config.toml` root `model` first, then the main/frontier default fallback; team fallback routing keeps it on the frontier lane. |

Team worker launches add another layer:

1. Explicit `--model ...` inside `RCS_TEAM_WORKER_LAUNCH_ARGS` wins.
2. Inheritable leader launch model args can be passed through to workers.
3. If no explicit/inherited model is present, the worker role's default model class selects the fallback model.
4. Fast roles such as `explore` and role names ending in `-low` use the low-complexity/spark fallback.

Use `rcs team status <team-name> --model-inspect` when you need inspect hints for a running team; the regular status path avoids spending model quota on summaries.

## Reasoning effort: supported places only

`.rcs-config.json` is **not** the general place to configure `model_reasoning_effort`. Do not add keys such as `reasoningEffort`, `modelReasoningEffort`, `reasoning`, or per-role reasoning maps to `.rcs-config.json`.

Supported reasoning-effort surfaces are:

- Active Codex `config.toml` root key: `model_reasoning_effort = "medium"`.
- `rcs reasoning <low|medium|high|xhigh>`, which edits the active Codex `config.toml`.
- `rcs --high` and `rcs --xhigh`, which pass `-c model_reasoning_effort="high|xhigh"` to Codex launch.
- Generated native agent TOML files, where RCS writes each role's built-in `reasoningEffort` metadata.
- Team worker launch args, for example:

```bash
RCS_TEAM_WORKER_LAUNCH_ARGS='-c model_reasoning_effort="low" --model gpt-5.3-codex-spark' \
  rcs team 3:explore "map the config surfaces"
```

Team runtime can also inject role-default reasoning for Codex workers when no explicit reasoning override is present. Explicit launch args win.

## Starter configs

JSON does not allow comments, so copy only the JSON blocks.

### Cost-saving starter

This keeps orchestration on the frontier default, routes standard workers to a cheaper standard model, and uses the spark lane for exploration/low-complexity work.

```json
{
  "env": {
    "RCS_DEFAULT_FRONTIER_MODEL": "gpt-5.5",
    "RCS_DEFAULT_STANDARD_MODEL": "gpt-5.4-mini",
    "RCS_DEFAULT_SPARK_MODEL": "gpt-5.3-codex-spark"
  },
  "models": {
    "default": "gpt-5.4-mini",
    "team": "gpt-5.5",
    "team_low_complexity": "gpt-5.3-codex-spark"
  }
}
```

### Max-quality starter

This keeps standard agents inheriting the frontier model by omitting `RCS_DEFAULT_STANDARD_MODEL`, while still preserving a fast spark lane for explicit low-complexity routing.

```json
{
  "env": {
    "RCS_DEFAULT_FRONTIER_MODEL": "gpt-5.5",
    "RCS_DEFAULT_SPARK_MODEL": "gpt-5.3-codex-spark"
  },
  "models": {
    "default": "gpt-5.5",
    "team": "gpt-5.5",
    "autopilot": "gpt-5.5",
    "forge": "gpt-5.5",
    "team_low_complexity": "gpt-5.3-codex-spark"
  }
}
```

## Verifying the effective config

After editing `.rcs-config.json` or `config.toml`, run setup/doctor from the same shell and project shape that will launch RCS:

```bash
rcs setup
rcs doctor
```

`rcs doctor` reports the resolved setup scope, Codex home, config path, hook coverage, prompt/skill/agent availability, and selected prompt-routing status. This verifies install wiring and which config tree RCS is checking.

A green `rcs doctor` is not proof that the active Codex profile can authenticate or run the selected model. For that, use the same shell/profile/project and run:

```bash
codex login status
rcs exec --skip-git-repo-check -C . "Reply with exactly RCS-EXEC-OK"
```

If behavior does not match your config, first confirm whether you are in user or project scope and whether `CODEX_HOME` is overriding the expected Codex home.

## Related docs and source surfaces

- Notification and OpenClaw config: [`docs/openclaw-integration.md`](../openclaw-integration.md)
- Provider abstraction: [`docs/reference/llm-provider-abstraction.md`](./llm-provider-abstraction.md)
- Project wiki config: [`docs/reference/project-wiki.md`](./project-wiki.md)
- Model routing source: `src/config/models.ts`
- Notification config source: `src/notifications/config.ts`, `src/notifications/types.ts`, `src/notifications/hook-config-types.ts`
- OpenClaw config source: `src/openclaw/types.ts`, `src/openclaw/config.ts`
- Prompt-routing config source: `src/hooks/triage-config.ts`
- Auto-nudge config source: `src/scripts/notify-hook/auto-nudge.ts`
- Wiki lifecycle config source: `src/wiki/types.ts`, `src/wiki/lifecycle.ts`
- Agent role definitions: `src/agents/definitions.ts`
- Native agent TOML generation: `src/agents/native-config.ts`
- Team model contract: `src/team/model-contract.ts`
- Scope/Codex home launch resolution: `src/cli/codex-home.ts`