What's the intended model-access workflow for OAuth login vs Coding Plan API key?

[c2b247007]

I want to make sure I'm using this the way it was designed. The README lists three paths: Z.AI OAuth (macOS), Z.AI/BigModel Coding Plan API key, and custom provider API key. But the config docs say the no-login TUI path "requires a non-empty options.apiKey" — which conflicts with the OAuth path.

Questions:

When using OAuth (zcode login), does the CLI use the session token for model calls, or does it still need an API key in config? The docs suggest API key is required even after login — is that right?
What's the intended flow for a user who just wants to use the CLI with their Z.ai account's free trial? Is the expectation "get a Coding Plan API key from the web console and put it in config" — i.e., the trial is a web-console thing, not a CLI thing?
Are main and lite models meant to be different Z.ai models, or can both point at GLM-5.3?
Does the CLI support multiple accounts/profiles (e.g. via config dir override), or is one ~/.zcode the expected model?

[kingsword09]

Good questions — I checked each one against the source. Answers inline:

1. OAuth: session token or API key?
   An API key — but you never configure it manually. After the token exchange, the runtime uses your Z.ai
   access token to resolve a Coding Plan API key (it finds or creates a key named zcode-api-key in your
   default org/project), then writes it into ~/.zcode/cli/config.json as provider.zai.options.apiKey along
   with baseURL: https://api.z.ai/api/anthropic. Model calls always go out with that key; the OAuth session
   (JWT) is only stored for ZCode-service flows. So the doc line "requires a non-empty options.apiKey" refers
   to the no-login custom provider path — after zcode login, the key is present because login put it there.
   No conflict, but I'll make the docs clearer on this.

2. Intended flow for a free-trial user?
   The expectation is: OAuth login → key auto-configured → works when the account has a Coding Plan
   subscription or pay-as-you-go credit. The free "Start Plan" trial specifically is desktop-app-only and not
   consumable by the CLI — see the analysis in OAuth login succeeds but model calls fail with "captcha verify failed" — trial quota unreachable via CLI #75 for why (per-request Aliyun captcha that only the desktop
   host can satisfy). So yes: for CLI use, attach a Coding Plan or PAYG balance to the account; the trial
   stays a desktop thing.

3. main vs lite?
   main is the conversation model; lite is used for lightweight work (compaction, title generation,
   subagents). They can both point at GLM-5.3 — valid config — but lite exists so cheap tasks don't burn
   flagship quota. OAuth defaults are main zai/glm-5.1, lite zai/glm-4.7.

4. Multiple accounts/profiles?
   One ~/.zcode per user is the expected model; there's no built-in profile switcher. Mechanically, both the
   config path and the credential store derive from $HOME (the credential store additionally honors a
   ZCODE_DATA_BASE_DIR override), so pointing HOME at a different directory effectively isolates a second
   account — state, plugins and all. That's a side effect of path resolution rather than a supported feature,
   so treat it as experimental. For per-project model overrides on the same account, zcode.json /
   .zcode/config.json in the working directory are the supported mechanism.