A Checklist Before Configuring AI Tools

Many AI tool failures are not model failures. They are plain configuration mismatches: the key is read from the wrong place, base_url has the wrong /v1 suffix, the model name is not the real API id, or the tool is calling a different endpoint than you expected.

This is not a full setup guide for one specific tool. It is a checklist you can use before configuring Codex, Claude Code, an OpenAI-compatible client, LiteLLM, one-api, New API, or an internal company gateway.

If the term “OpenAI-compatible API” is still fuzzy, start with /en/posts/what-is-openai-compatible-api.

First, Name the Layer You Are Configuring

A single AI request usually crosses several layers:

1. Local tool: Codex, Claude Code, an editor plugin, or your script.
2. SDK or client: OpenAI SDK, Anthropic SDK, LangChain, LiteLLM, and so on.
3. Gateway or relay: a team API gateway, relay provider, or reverse proxy.
4. Upstream model provider: OpenAI, Anthropic, Google, or another model service.

Configuration gets messy when fields from different layers are mixed together. A common example: the tool asks for base_url, but you paste the full /v1/chat/completions endpoint. Another: the tool expects an Anthropic endpoint, but you give it an OpenAI-compatible endpoint.

Before editing config files, write down three sentences:

• Which API shape is the tool supposed to call: OpenAI, Anthropic, or a provider-specific API?
• Is there a relay or gateway in the middle?
• Is this key from the upstream provider, the relay provider, or an internal gateway?

If those answers are unclear, later error codes will be easy to misread.

Key: Check Source, Permission, Quota, and Storage

For the API key, check at least four things:

• Source: official provider, relay provider, or internal company gateway.
• Permission: whether it can call the target model and endpoint.
• Quota: whether the project, account, subscription, or relay balance can still spend.
• Storage: whether the tool actually reads the place where you stored it.

Do not put keys in the repository. Better options include user-level key files, OS credential storage, CI secrets, and deployment platform secrets. For local command-line tools, a separate key file is often easier to reason about than a project .env that might be committed by mistake.

Logs should not print full keys either. Keep only a short masked form:

sk-proj-abc...xyz

When debugging a 401, it is useful to confirm which key the tool loaded. It is not useful to paste the full key into an issue, chat thread, or screenshot.

base_url: Use the Service Root, Not a Random Full Path

base_url is one of the easiest fields to get wrong.

Many OpenAI-compatible APIs use:

https://api.example.com/v1

Some tools append /v1 themselves, so they expect:

https://api.example.com

Some relay providers expose separate OpenAI and Anthropic entry points:

https://relay.example.com/v1
https://anthropic.relay.example.com

Do not guess from habit. Check what the tool means by base_url:

• Is it the API root or a full endpoint?
• Should it include /v1?
• Does the tool append /chat/completions, /responses, or /messages?
• Does that URL support Anthropic messages, or only OpenAI-compatible calls?

The fastest confirmation is a tiny smoke test. Ask for one short response before letting an agent edit code.

model: Use the Real API Model ID

The model name in your config is not always the marketing name you see on a product page. The request needs the API model id accepted by the platform you are calling.

Keep these separate:

• Model family: GPT, Claude, Gemini.
• Product name: chat product, IDE plugin, subscription tier.
• API model id: the value in the request body’s model field.
• Relay alias: a model name remapped by the relay provider.

If you call through a relay, use the model list from that relay dashboard. It may expose upstream names directly, or it may use aliases. An alias may not support every endpoint, context length, tool-calling feature, or vision feature.

A practical split:

• Default chat: stable, cheap, and low latency.
• Code edits: enough context and reliable tool behavior.
• Complex refactors: stronger reasoning, with acceptable cost and latency.
• Batch jobs: cheap, retryable, and stable output format.

For coding agents specifically, continue with /en/posts/choose-model-for-coding-agent.

endpoint: Verify the Interface the Tool Actually Calls

Many services are described as “OpenAI-compatible,” but the actual endpoint matters:

• /v1/chat/completions
• /v1/responses
• /v1/completions
• /v1/embeddings
• /v1/images
• Anthropic-style /v1/messages

A service can support Chat Completions without supporting Responses. A model can chat without supporting embeddings. A relay can expose Claude while still requiring an Anthropic-shaped request rather than an OpenAI SDK request.

When debugging, do not inspect only base_url. Inspect the final request path. If debug logs are available, confirm:

• The request method.
• The final URL.
• The model field in the body.
• Whether the error came from the gateway or the upstream provider.

If logs include prompts, user data, or keys, redact them before sharing.

Proxy and Network: Separate Local, Tool, and Server-Side Proxies

Proxy issues often look like authentication or upstream failures.

There are three places to separate:

• Local proxy: whether your shell has HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY.
• Tool proxy: whether the AI tool has its own proxy setting.
• Server-side proxy: whether the relay or company gateway needs a proxy to reach the upstream provider.

Being able to open a provider website in the browser does not prove that a CLI tool can reach the API. The browser may use system proxy settings while your terminal does not. Your terminal may have proxy variables that a GUI app ignores. Your machine may reach the relay while the relay cannot reach its upstream.

A minimal network checklist:

1. Can your machine resolve the target domain?
2. Can it establish HTTPS?
3. Does the proxy require authentication?
4. Does the tool inherit shell environment variables?
5. Can the relay or gateway reach the upstream provider?

When you see 429 or 500, do not ignore network and proxy layers. Timeouts, connection reuse problems, and proxy-level rate limits can be wrapped into confusing errors. For common status-code debugging, see /en/posts/debug-ai-api-401-429-500.

Logs: Turn Them On, Then Redact

AI API logs should be detailed enough to debug, but not detailed enough to leak secrets.

Good fields to record:

• Trace id or request id.
• Time, tool version, and config profile.
• base_url domain and path, without credentials.
• Endpoint, model, status code, and error type.
• Input and output token counts if usage data is returned.
• Cache hits, retries, and retry count.

Avoid logging:

• Full API keys.
• Private user data.
• Full long prompts.
• Business database records.
• Production cookies, sessions, or JWTs.

If you need verbose logs, enable them for one minimal request and turn them off after the investigation. Before sharing logs, search for sk-, Bearer, Authorization, cookie, session, and token.

A Minimal Validation Flow

I usually validate in this order:

1. Call a cheap model and ask for one short sentence.
2. Switch to the target model and ask for the same short sentence.
3. Before enabling tools, file access, or agent mode, run another small task.
4. Try one realistic but low-risk task to test context and output stability.
5. Only then use it on a real project or production workflow.

Do not start by asking an agent to edit dozens of files. Before configuration is stable, complex tasks mix authentication, model choice, context length, tool permissions, network behavior, and code errors into one noisy failure.

Final Checklist

• The key comes from the right platform and is not stored in the repository.
• The key has permission for the target model and endpoint.
• base_url includes or omits /v1 according to the tool’s rules.
• model is a real API id accepted by the platform.
• The endpoint matches the protocol: Responses, Chat Completions, Messages, and so on.
• Local proxy, tool proxy, and server-side proxy are not being confused.
• Logs can identify the request and are already redacted.
• A minimal smoke test has passed.

The point is not to memorize one perfect sample config. The point is to separate key, base URL, model id, endpoint, proxy, and logs. Once those lines are clear, 401, 429, and 500 errors become much easier to place.