API de Claude Code y Codex: protocolo, configuración y primera prueba
Una guía práctica para validar los contratos API distintos de Claude Code y Codex.
Índice
API de Claude Code y Codex: protocolo, configuración y primera prueba
La etiqueta «OpenAI-compatible» no basta para usar una misma configuración en ambos clientes. Claude Code espera el contrato Anthropic Messages; un proveedor personalizado de Codex utiliza OpenAI Responses. Antes de comparar precios, confirma la guía específica, la Base URL, el campo de autenticación y el Model ID vigente.
Para probar BetterToken, empieza por la guía de Claude Code o la guía de Codex. Son rutas separadas por protocolo y la API Key se crea en tu propia cuenta. Tras una solicitud corta, Dashboard permite revisar estado, modelo, tokens input/output/cache y cargo.
Dos contratos de cliente
| Cliente | Qué debe quedar comprobado | Valor de BetterToken que hay que verificar |
|---|---|---|
| Claude Code | Acceso Anthropic-compatible Messages y variables de autenticación documentadas | https://bettertoken.ai; Claude Code añade /v1/messages |
| Codex CLI/App | Proveedor personalizado que use Responses, no solo Chat Completions | https://www.bettertoken.ai/v1 con wire_api = "responses" |
La guía actual de Claude Code usa ANTHROPIC_BASE_URL y ANTHROPIC_AUTH_TOKEN. No añadas /v1: el cliente compone la ruta Messages. Codex carga el proveedor desde ~/.codex/config.toml y la clave desde BETTERTOKEN_API_KEY.
La referencia de configuración de Codex de OpenAI y la documentación de Claude Code son las fuentes primarias del cliente. Los valores del proveedor siempre se vuelven a comprobar en su documentación actual.
Comprobación mínima
model_provider = "custom"
model = "YOUR_MODEL_ID"
[model_providers.custom]
base_url = "https://www.bettertoken.ai/v1"
env_key = "BETTERTOKEN_API_KEY"
wire_api = "responses"
requires_openai_auth = falseYOUR_MODEL_ID es un marcador intencional. La disponibilidad y los IDs cambian, así que copia un identificador completo y actual desde el catálogo o el diálogo de configuración. No guardes una clave de proveedor personalizado en ~/.codex/auth.json.
En Claude Code comprueba estas variables de protocolo:
{
"env": {
"ANTHROPIC_BASE_URL": "https://bettertoken.ai",
"ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY"
}
}La guía vigente indica el archivo y los campos opcionales. Una API Key nunca debe aparecer en prompts, issues, capturas ni repositorios.
Prueba corta antes de la carga real
- Abre la guía actual de la versión exacta del cliente.
- Crea una clave de prueba propia, no una cuenta compartida.
- Copia Base URL y Model ID de la documentación o Dashboard.
- En Claude Code confirma ruta y variables; en Codex, proveedor, variable de entorno y
wire_api = "responses". - Empieza en un repositorio vacío sin secretos de producción.
- Envía una tarea pequeña y acotada.
- Registra estado, modelo, tokens, reintentos visibles y cargo final. Después repite una tarea representativa idéntica.
Coste y errores iniciales
El precio del token de entrada no equivale al coste de una tarea de agente. El contexto, las salidas de herramientas, la caché, los reintentos y la longitud de salida afectan al total. Para cada opción registra Model ID, tokens input/output/cache, solicitudes, errores, reintentos y cargo final. Consulta la página de precios actual de BetterToken; una cifra antigua solo es histórica.
| Síntoma | Revisar primero |
|---|---|
401 | Clave, nombre del campo y espacios pegados |
404 / fallo de conexión | Base URL correspondiente al protocolo, no una ruta HTTP completa |
model not found | Model ID completo y vigente del mismo proveedor y grupo de claves |
| Error de modo en Codex | wire_api = "responses", no solo Chat Completions |
429 | Límite del endpoint, Retry-After y si es seguro reintentar |
| Streaming interrumpido | Soporte de streaming, red y estado de la solicitud |
| Cargo poco claro | Modelo, registros de tokens y reintentos |
Cambia un único parámetro por prueba. Así podrás atribuir el fallo a URL, clave, modelo o configuración.
Decidir con un test registrado
Esta lista no es un ranking de velocidad, estabilidad ni precio mínimo. Sirve para comprobar dos contratos de cliente. Lee los documentos el día del test y decide tras una misma tarea de repositorio, usando resultado, errores, tokens y cargo final.
Abre la guía BetterToken de Claude Code o Codex, crea una clave separada y verifica la primera solicitud en Dashboard antes de llevar trabajo a producción.
