CLI Agent 首次請求失敗：一行設定中的三個名稱

Context: I run a CLI agent against one gateway. The whole setup is one provider block in one config file — and three different things in that block are called some kind of "name". I got them mixed up on 23 September 2026, and it cost me an evening.

What I did

I pasted the provider block, exported the key, and sent a request.

# ~/.codex/config.toml
model_provider = "decloud"

[model_providers.decloud]
base_url = "https://macdecloud.com/v1"
env_key  = "DECLOUD_API_KEY"   # a NAME, not the secret
wire_api = "responses"

What broke

My first request died on a 404 that reads like a broken model:

model not found or disabled    (HTTP 404)

The model was fine. The alias it pointed at had not been created yet — the third of the three names. In this setup a 404 means "this name is not known here", and one of the three names is a name I had to create myself before the first call.

Then the other two names turned out to be confused with each other.

1. env_key wants the variable's name; I pasted the secret. The field is called env_key, so it reads like it wants a key. It wants the name of the environment variable that holds the key:

Missing environment variable

2. An alias is not a permission. Once the alias existed, the call still failed:

model "<alias target>" is not allowed for this api key    (HTTP 403)

3. There is no endpoint that answers "what may this key call". I went looking for a cheap way to ask. /v1/me, /v1/key and /v1/usage all came back 404. The answer lives in the console, not in the API.

The two codes are not the same question

This was the most useful thing I wrote down all evening. Both numbers arrive attached to the model name, and they mean opposite things:

What came back	Code	What it means	What to change
`model not found or disabled`	404	this name is not known here	create the alias, or fix the model id
`... is not allowed for this api key`	403	the model exists; this key may not use it	the key's own model scope
`Missing environment variable`	—	the variable the config names does not exist	`env_key` vs what you exported
`rate limit exceeded`	429	too fast	slow the probe down

The catalogue endpoint makes this worse before it makes it better. It returns the gateway's full list, and I quietly assumed that a listed model was a usable model. It is not. A catalogue describes what exists; a permission list describes what you may call. Only one of those two is written in the config file.

How I fixed it

I stopped treating the block as "fields to fill" and wrote down the three names and their jobs:

one name is the credential's name — the environment variable (env_key → DECLOUD_API_KEY);
one is the secret — the value inside that variable, exported in the shell, never written into the file;
one is the alias — the model name the request carries, which the key must separately be allowed to use.

With that mapping written down, every failure turned into a question I could answer: which of the three names does this error belong to?

What I would do differently

One line, before touching anything:

cp config.toml config.toml.bak

I did not, and an editor save accident wiped the file mid-session. The only reason that evening ended with a working setup instead of a rebuild is that an earlier backup existed. A config file for a developer tool accumulates months of small decisions; it is not disposable.

Takeaways

Read the error, not the sentence you expected. Missing environment variable is about a name, not about the secret.
A catalogue is not a permission list. Check the key's own scope before you touch the model name.
Back up the config before you edit it — and if the API cannot tell you what a key may call, write that answer down from the console once.