# 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 what should be changed in the current local setup.

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

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:

- 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.
- Treat a route as production-safe only when it validates native tool/function calling, not just chat completion.

## `/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.

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 gpt-5.3-codex
/model gpt-5.5
/model default
```

Do not use `/model` as the primary way to configure Clavue. If `/model` and `/provider` disagree, the 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.

## 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.
```
