TL;DR En
~/.claude/settings.json, añade un bloquemodelPickercon las dos o tres filas que usas y"replaceBuiltInOptions": true. Sin esetrue, una fila que ya está en la lista integrada se ignora y no ves ningún cambio.
Abres /model y te salen Default, Fable, Opus, Sonnet, Haiku y las variantes de 1M, cuando tú solo cambias entre dos. Y si trabajas contra un gateway o Bedrock, el modelo aparece con su ID en crudo y con un aviso de modelo desconocido. Desde la v2.1.242, el setting modelPicker decide qué filas lista el picker, en qué orden y con qué etiqueta. Y desde la v2.1.257, behavesAs le dice a Claude Code qué modelo conocido hay detrás de un ID que no reconoce.
Cómo funciona
modelPicker es un objeto con una lista options y un booleano replaceBuiltInOptions. Cada fila lleva un model obligatorio y, si quieres, label, description y behavesAs. El campo model acepta lo mismo que --model: un alias como opus, un ID de Anthropic o un ID en el formato de tu proveedor.
El detalle que decide si el tip funciona o no: con replaceBuiltInOptions en false (el valor por defecto), tus filas se añaden detrás de la lista integrada, y una fila cuyo modelo ya está en esa lista se omite. Es decir, si listas opus y haiku sin el true, el picker queda exactamente igual. Con true, el picker muestra solo tus filas, Default y una fila para el modelo con el que ya está corriendo la sesión.
Resultado, con dos filas y la lista integrada fuera (vista orientativa, el picker es una interfaz interactiva):
> /model
1. Default (recommended)
> 2. Opus (diario) Todo lo que no sea un arreglo rápido
3. Haiku (tareas ligeras) Scripts, renombrados, preguntas sueltas
Enter to set as default · s to use this session only
Enter y s siguen significando lo mismo que siempre: Enter guarda el modelo como tu default y s lo usa solo en esta sesión.
Configurarlo
1. Escribe tus filas en el settings de usuario
En ~/.claude/settings.json:
{
"modelPicker": {
"replaceBuiltInOptions": true,
"options": [
{
"model": "opus",
"label": "Opus (diario)",
"description": "Todo lo que no sea un arreglo rápido"
},
{
"model": "haiku",
"label": "Haiku (tareas ligeras)",
"description": "Scripts, renombrados, preguntas sueltas"
}
]
}
}
El orden de la lista es el orden del picker, salvo que una fila esté deshabilitada: esa baja al final con el motivo al lado. Sin label, Claude Code pone el nombre integrado si conoce el modelo y el ID si no. Sin description, escribe una segunda línea genérica. La etiqueta cambia lo que lees, no el modelo que corre.
2. Ponlo donde Claude Code lo lee
Claude Code lee modelPicker en tres sitios: los managed settings de tu organización, el flag --settings y tu ~/.claude/settings.json. Lo ignora en .claude/settings.json y en .claude/settings.local.json, para que un repositorio clonado no te pueda reetiquetar el picker. Y no mezcla listas: la fuente más alta que defina la clave aporta la lista entera. Si tu empresa fija una, la tuya no se lee. Es la misma lógica que cuando chocan dos configuraciones.
Para probar una lista sin tocar ningún archivo, pásala por --settings:
claude --settings '{"modelPicker":{"replaceBuiltInOptions":true,"options":[{"model":"opus","label":"Opus (diario)"},{"model":"haiku","label":"Haiku (tareas ligeras)"}]}}'
3. Un ID de gateway o de Bedrock sin el aviso de modelo desconocido
Si arrancas con un ID que Claude Code no reconoce, el inicio de la sesión te lo dice y asume una ventana de 200K:
⚠ Model "my-gateway-opus" isn't recognized · context assumed to be 200k tokens · ...
Añade la fila con behavesAs apuntando al ID de un modelo que tu versión sí conoce. Claude Code le aplica las capacidades y el effort por defecto de ese modelo; la etiqueta y el ID que viaja en cada petición no cambian:
{
"model": "my-gateway-opus",
"label": "Opus (gateway)",
"behavesAs": "claude-opus-5-5"
}
La alternativa es una entrada en modelOverrides que mapee el ID de Anthropic al tuyo. Las dos consiguen lo mismo; behavesAs lo deja escrito en la propia fila del picker.
Referencia
| Campo | Tipo | Qué hace |
|---|---|---|
options[].model |
string, obligatorio | Lo que recibe --model: alias, ID de Anthropic o ID del proveedor |
options[].label |
string | Texto de la fila. No cambia el modelo que corre |
options[].description |
string | Segunda línea de la fila |
options[].behavesAs |
string, v2.1.257+ | ID de un modelo conocido cuyas capacidades hereda la fila |
replaceBuiltInOptions |
booleano, false por defecto |
true esconde la lista integrada; false añade tus filas detrás y omite las repetidas |
Si no ves ningún cambio
Primero mira el arranque de la sesión. Una clave mal escrita no tumba el archivo: Claude Code la omite y te avisa. Esto es lo que imprime si replaceBuiltInOptions llega como texto en lugar de booleano:
These settings entries were skipped because this version of Claude Code can't apply them; the rest of each file is in effect:
--settings (inline JSON) (modelPicker.replaceBuiltInOptions): "replaceBuiltInOptions" must be true or false; received string. This entry was ignored (the rows are added to the built-in lineup).
Tres cosas más que filtran tus filas:
- Una fila que la sesión no puede servir (un modelo retirado o al que tu organización no tiene acceso) se elimina sin aviso en el picker. Si no sobrevive ninguna, vuelve la lista integrada.
- Una lista
availableModelssigue mandando: una fila fuera de esa lista no aparece. - Con
replaceBuiltInOptions: truedesaparecen también las filas de 1M. Si una te hace falta,modelacepta lo mismo que--model; aquí tienes cómo funcionan esas variantes.
Documentación oficial: modelPicker
Requisitos: modelPicker llegó en la v2.1.242 y behavesAs en la v2.1.257. Probado en la v2.1.303.