# Clavue Provider And Model Best Practices

This document describes how Clavue should be configured for the fastest reliable coding workflow, which files own each setting, how `/provider` and `/model` differ, and how the v9 provider/model mode pickers should be used.

## Executive Verdict

The current OpenAI-native setup is now the high-performance best-practice baseline when the gateway validation remains green.

- Active profile: `ttqq2`
- Provider mode: OpenAI-native through `https://ttqq.inping.com`
- Current routing: `gpt-5.5` for Primary/Sonnet/Opus and `gpt-5.3-codex` for Haiku
- Recommended preset: `gpt_5_5_max`
- Validation requirement: `gpt-5.5` must keep proving the Responses function-calling route before Clavue trusts it for native coding workflows
- Confirmed supported route on this gateway: `gpt-5.3-codex`
- Confirmed avoid routes on this gateway right now: `gpt-5.4`, `gpt-5.3-codex-spark`

The maximum-capability baseline is therefore:

```text
Provider profile: ttqq2
Model mode: OpenAI-native
Routing preset: gpt_5_5_max
Primary: gpt-5.5
Haiku: gpt-5.3-codex
Sonnet: gpt-5.5
Opus: gpt-5.5
```

The conservative fallback baseline is:

```text
Provider profile: ttqq2
Model mode: OpenAI-native
Primary: gpt-5.3-codex
Haiku: gpt-5.3-codex
Sonnet: gpt-5.3-codex
Opus: gpt-5.3-codex
```

Use the conservative fallback only if `clavue provider validate ttqq2` stops proving full Responses function calling for `gpt-5.5`.

## Configuration Ownership

Clavue should be configured from the `.clavue` namespace. `.claude` should exist only for intentional compatibility with older Claude Code assets.

| Surface | File Or Command | Purpose |
|---|---|---|
| Provider profiles | `~/.clavue/.clavue.json` | Stores saved provider profile metadata, active profile id, and capability cache. |
| Provider credentials | `~/.clavue/.credentials.json` | Stores provider credentials. Do not commit or paste this file. |
| Global user settings | `~/.clavue/settings.json` | Stores global model/env/permission/output preferences. |
| Project settings | `.clavue/settings.json` | Stores committed project-wide Clavue behavior. |
| Local project overrides | `.clavue/settings.local.json` | Stores uncommitted personal overrides for one project. |
| User skills | `~/.clavue/skills/<name>/SKILL.md` | Personal skills available in every project. |
| Project skills | `.clavue/skills/<name>/SKILL.md` | Project-specific skills loaded from the repo. |
| Legacy compatibility | `~/.claude/*`, `.claude/*` | Read only when compatibility is intentional. Do not create new Clavue assets here. |

Current local issue:

```json
{
  "plansDirectory": ".claude/plans"
}
```

Current releases normalize this legacy value to the Clavue path at runtime:

```json
{
  "plansDirectory": ".clavue/plans"
}
```

Current local skills issue:

```text
~/.clavue/skills exists but is empty.
~/.claude/skills still contains legacy items.
```

Recommended action: migrate any still-needed legacy skills into `~/.clavue/skills/<skill-name>/SKILL.md`. Do not blindly replace every `.claude` string in source code, because some `.claude` references are deliberate compatibility paths.

## `/provider` Is The Source Of Truth

Use `/provider` or `clavue provider` for API URL, credential type, provider mode, and slot routing. With no arguments it now starts at a mode picker instead of jumping directly into a low-level profile screen.

Provider mode choices:

| Mode | Use When | Result |
|---|---|---|
| `组合模式` | Different slots should use different model families, model strengths, or provider routes. | Opens the hybrid-compatible manager and requires explicit Primary / Haiku / Sonnet / Opus setup. |
| `单独模式` | One model family and one provider profile should own the whole route. | Opens the focused family/profile setup flow. |
| `完整 API 入口` | You need official login, custom API setup, CCR proxy setup, import, validation, repair, or manual profile management. | Opens the full provider setup control center. |

Useful commands:

```bash
clavue provider list
clavue provider current
clavue provider validate ttqq2
clavue provider matrix ttqq2
clavue provider probe ttqq2
clavue provider repair ttqq2
clavue provider use ttqq2
```

When a provider profile is activated, Clavue writes the provider route into `~/.clavue/settings.json` under `env`, including:

```text
ANTHROPIC_BASE_URL
ANTHROPIC_MODEL
ANTHROPIC_SMALL_FAST_MODEL
ANTHROPIC_CUSTOM_MODEL_OPTION
ANTHROPIC_DEFAULT_OPUS_MODEL
ANTHROPIC_DEFAULT_SONNET_MODEL
ANTHROPIC_DEFAULT_HAIKU_MODEL
CLAUDE_CODE_SUBAGENT_MODEL
```

It also writes the top-level `model` setting to the profile's primary model.

Best practice:

- Start with `/provider` for any durable provider, credential, or slot-routing change.
- Use `组合模式` when subagents, planner, fast helper, or main session should not all use the same model route.
- Use `单独模式` when a single validated provider/model family is enough for all roles.
- Change provider and slot routing through `/provider`, not by hand-editing environment variables.
- Run `clavue provider validate <profile>` after every model or gateway change.
- Run `clavue provider matrix <profile>` when deciding which GPT/Codex route is safe.

### Product policy: open tools first, health may narrow

Clavue's runtime coding route policy is **open-tools first**:

- Any **user-configured** provider route keeps a full coding surface by default.
  Capability snapshots may choose transport (messages / responses / chat
  completions) and inform warnings, but they must **not** hide tools or force a
  chat-only workflow solely because function calling is unvalidated.
- **Permission mode** (`/permissions`) is the operator's explicit execution
  boundary — not capability probes.
- **Provider health** (ledger: degraded / broken) *is* allowed to narrow
  workflow tools, force strict recovery, and surface `qualityTier` as
  `degraded` / `blocked` so orchestration can enter `fallback_chain`.

Validation (`provider validate` / matrix) remains the recommended gate before
**trusting a new gateway for production workloads**, but missing validation no
longer means Clavue refuses the coding surface. Prefer validate-then-use for
new endpoints; treat runtime health demotions as the safety net for
already-configured routes.

## `/model` Is A Main-Session Override

`/model` changes the main conversation model. It does not reconfigure the provider profile, base URL, credential, or all provider slots. With no arguments it now asks for combination or single-mode intent before opening the relevant picker.

Model mode choices:

| Mode | Behavior |
|---|---|
| Combination mode | Uses the current `/provider` Primary slot as the main session model. Haiku, Sonnet, Opus, subagent, and planning roles stay owned by `/provider`. |
| Single mode | Opens the direct model picker for the current main session. |
| `/model <model-name>` | Keeps the fast explicit override behavior for the current session. |

Selection priority for the main loop is:

```text
1. Current session `/model` override
2. Startup model override
3. ANTHROPIC_MODEL from settings/env
4. `model` in settings
5. Built-in default
```

Use `/model` for temporary session control:

```text
/model
/model default
/model gpt-5.3-codex
/model gpt-5.5
```

Do not use `/model` as the primary way to configure Clavue. If `/model` and `/provider` disagree, the main session may look correct while subagents, planner routes, Opus/Sonnet/Haiku defaults, and fast model behavior remain inconsistent.

## Recommended Model Strategy

Clavue has four user-facing slot concepts:

| Slot | Intended Use | Current Best Choice On `ttqq2` |
|---|---|---|
| Primary | Main session and default coding loop | `gpt-5.5` for maximum validated performance, or `gpt-5.3-codex` as conservative fallback |
| Haiku | Fast/small helper route | `gpt-5.3-codex` |
| Sonnet | Workhorse/helper route | `gpt-5.5` for maximum validated performance, or `gpt-5.3-codex` as conservative fallback |
| Opus | Planning/high-capability route | `gpt-5.5` for maximum validated performance, or `gpt-5.3-codex` as conservative fallback |

Derived roles such as subagent, plan, explore, general, team, and guide are expanded from these provider slots. This is why `/provider` matters more than `/model` for complete behavior.

Current `ttqq2` probe result:

```text
gpt-5.5: reachable, OpenAI Responses compatibility route, full Responses function calling available
gpt-5.3-codex: reachable, OpenAI Responses compatibility route, full Responses function calling available
gpt-5.4: chat-only, avoid for native coding workflows here
gpt-5.3-codex-spark: chat-only, avoid for native coding workflows here
```

Decision rule:

- If you want maximum capability, use the `gpt_5_5_max` preset and keep `gpt-5.5` for Primary/Sonnet/Opus.
- If the gateway stops validating full Responses function calling for `gpt-5.5`, fall back to `gpt-5.3-codex` everywhere until validation recovers.
- Do not use `gpt-5.4` on `ttqq2` until `clavue provider matrix ttqq2` says it supports a native coding route.

## Permission And Efficiency Review

Current global permissions are optimized for speed, not safety:

```text
Read(*)
Edit(*)
Write(*)
Bash(rm *)
WebFetch(*)
MCP(*)
permissions.defaultMode = auto
skipAutoPermissionPrompt = true
```

This is high-throughput on a trusted local machine, but it is not the safest default. It can be acceptable for a single-user trusted coding workstation, but it should not be called universal best practice.

Safer high-efficiency baseline:

```json
{
  "permissions": {
    "allow": [
      "Read(*)",
      "Edit(/Users/lu/codebase/**)",
      "Write(/Users/lu/codebase/**)",
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(npx *)",
      "Bash(node *)",
      "Bash(rg *)",
      "Bash(find *)",
      "Bash(ls *)",
      "Bash(cat *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ],
    "defaultMode": "auto"
  },
  "skipAutoPermissionPrompt": true
}
```

Maximum-speed trusted-machine baseline:

```json
{
  "permissions": {
    "allow": [
      "Read(*)",
      "Edit(*)",
      "Write(*)",
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(npx *)",
      "Bash(node *)",
      "WebFetch(*)",
      "MCP(*)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ],
    "defaultMode": "auto"
  },
  "skipAutoPermissionPrompt": true
}
```

Avoid permanently allowing broad destructive commands such as `Bash(rm *)` unless the machine and workflow are fully trusted.

## Unified gateway / official compat

Clavue maps NewAPI, Sub2API, and official OpenAI / Claude / DeepSeek / GLM / Grok / Kimi through one catalog (`src/services/api/providerCompat.ts`): host, model family, transport, tool style (including DeepSeek/Grok `reasoning_content` replay), and fallback context windows. Errors go through `gatewayErrorAdapt` so a NewAPI 400 wrapper is never painted as a missing Authorization header.

Live `/v1/models` `max_input_tokens` / `context_length` still win when the gateway publishes them.

## Exact Setup Procedure

For the conservative fallback route:

```bash
clavue provider
```

Then configure or edit profile `ttqq2`:

```text
Base URL: https://ttqq.inping.com
Mode: OpenAI-native
Primary: gpt-5.3-codex
Haiku: gpt-5.3-codex
Sonnet: gpt-5.3-codex
Opus: gpt-5.3-codex
```

Validate:

```bash
clavue provider validate ttqq2
clavue provider matrix ttqq2
clavue provider current
```

For the performance route:

```text
Base URL: https://ttqq.inping.com
Mode: OpenAI-native
Routing preset: gpt_5_5_max
Primary: gpt-5.5
Haiku: gpt-5.3-codex
Sonnet: gpt-5.5
Opus: gpt-5.5
```

Validation must continue to show:

```text
Full Responses function calling is available
workflow=compat_native
responsesReasoningXHigh=true
```

If validation changes to chat-only or compatibility warnings become functional errors, immediately switch back to `gpt-5.3-codex` everywhere.

## Beyond Default Claude Code

The way to make Clavue materially stronger than default Claude Code is not one magic model string. It is the combination of:

- Provider-first routing instead of ad hoc environment variables
- Explicit Primary/Haiku/Sonnet/Opus slots
- Live route validation and matrix probing
- OpenAI Responses compatibility checks before trusting GPT/Codex models
- Adaptive GPT-5.5 effort and verbosity gears that spend more capability on high-risk development work and downshift for lightweight routes
- `.clavue`-scoped config, skills, teams, memory, and plans
- Fast trusted-machine permission mode with targeted destructive-command denial
- Consistent `/provider` baseline plus temporary `/model` overrides only when needed

The current setup is close to the maximum-capability baseline. Remaining cleanup items:

- Prefer changing `plansDirectory` from `.claude/plans` to `.clavue/plans`; current Clavue builds normalize the legacy value automatically, but the settings file should still be cleaned up.
- Migrate needed legacy user skills from `~/.claude/skills` into `~/.clavue/skills`.
- Keep `gpt-5.5` validation fresh after gateway, model, provider, package, or npm release changes.
- Remove or deny broad destructive permissions such as `Bash(rm *)` if this configuration will be reused outside a fully trusted machine.

## Maintenance Checklist

Run this after every provider, gateway, model, package, or npm release change:

```bash
clavue provider current
clavue provider validate ttqq2
clavue provider matrix ttqq2
clavue provider probe ttqq2
npx -y clavue --version
```

Expected healthy result:

```text
Provider is active.
Primary/Haiku/Sonnet/Opus routes are reachable.
Native coding workflow is compat_native or better.
Tool/function calling is verified, not merely chat completion.
No new assets are created under .claude except intentional compatibility files.
```