Updated 2026-08-05
How to connect an Alibaba Cloud API key to local Codex
The reliable route is local Codex plus a custom provider. Use an ordinary Alibaba Cloud Model Studio API key, copy the matching workspace API Host, choose a model that supports the Responses API, keep the secret outside `config.toml`, and verify the session from a fresh process. The examples below use Beijing and `qwen3.7-max`; replace both only with values confirmed in your own Model Studio console.
1. Check the credential before editing Codex
Confirm that the credential is an ordinary Model Studio API key, not a Token Plan or Coding Plan key. Current workspace keys commonly use the `sk-ws` prefix, while older `sk-` keys can remain valid. A plan credential such as `sk-sp` belongs to a different entitlement and endpoint path.
In the Alibaba Cloud console, copy the API Host shown with the key and record the region and workspace. Also check model permissions and IP restrictions. A syntactically valid key can still fail when the selected model, source IP, region, or workspace is outside its permissions.
| Item | What to verify |
|---|---|
| Key class | Ordinary Model Studio API key, not a plan-specific credential |
| Workspace | The workspace that owns the key and exposes the selected model |
| Region | The key and API Host belong to the same region |
| Permissions | The target model and your source IP are allowed |
| Protocol | The chosen model supports the Responses API for current Codex |
Sources checked
- Alibaba Cloud Model Studio API key guide - Primary source for key creation, API Host display, workspace ownership, permissions, and regions.
2. Install or update the local Codex client
Use a current Codex release for the Responses API route. Alibaba's current guide warns that modern Codex no longer accepts the older `wire_api = "chat"` path. If a model only supports Chat Completions, do not present it as a current Codex setup; choose a Responses-capable model instead.
Install or update the official npm package, then open a new terminal so the shell sees the current executable and environment. This article configures the local CLI; it does not configure Codex Cloud.
npm install -g @openai/codex@latest
codex --versionSources checked
- OpenAI Codex repository - Official source for the Codex CLI package and installation command.
- Alibaba Cloud Model Studio Codex guide - Primary source for current Responses API compatibility and Alibaba's Codex examples.
3. Export the key without putting it in the TOML file
Use a dedicated environment-variable name so the Alibaba credential cannot be mistaken for an OpenAI credential. OpenAI's custom-provider format lets `env_key` reference the variable you choose, so `DASHSCOPE_API_KEY` is clearer than overloading `OPENAI_API_KEY`.
The command below sets the key only for the current shell. For persistent desktop or IDE use, store it with an approved operating-system or team secret mechanism and make sure the application process receives the variable. Never commit the key, paste it into public logs, or place it directly in `config.toml`.
export DASHSCOPE_API_KEY="replace-with-your-own-api-key"
mkdir -p ~/.codex4. Add the Alibaba provider to ~/.codex/config.toml
Use a non-reserved provider ID and the API Host for the key's workspace. The example below uses the Beijing host pattern documented by Alibaba. Replace `{WorkspaceId}` with the actual workspace ID, including no braces. For a Singapore key, use its Singapore workspace host; never mix a Beijing key with a Singapore host.
The model example, `qwen3.7-max`, is documented by Alibaba as a Responses-compatible route. Model availability can change, so use the exact ID shown in the current Alibaba documentation and allowed by your workspace rather than guessing from a marketing name.
| Region | Base URL pattern |
|---|---|
| Beijing | https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 |
| Singapore | https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1 |
model = "qwen3.7-max"
model_provider = "alibaba-model-studio"
[model_providers.alibaba-model-studio]
name = "Alibaba Cloud Model Studio"
base_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
env_key = "DASHSCOPE_API_KEY"
wire_api = "responses"Sources checked
- OpenAI custom model providers - Primary source for provider IDs, `model_provider`, `base_url`, `env_key`, and Responses API wiring.
- Alibaba Codex pay-as-you-go configuration - Primary source for workspace host patterns, region matching, and the Qwen Responses example.
5. Start a fresh session and verify the actual route
Open a new terminal that has `DASHSCOPE_API_KEY`, then start `codex`. Send a small, non-sensitive test prompt before opening a large repository. Success means the session starts with the configured Qwen model and returns a response without authentication, model, or protocol errors.
Do not use a third-party health-check badge as the only proof. Alibaba notes that some switching tools can report HTTP 400 even when a real Codex request works. The end-to-end Codex session is the verification that matters.
test -n "$DASHSCOPE_API_KEY" && echo "API key variable is set"
codex6. Optional model metadata and team rollout
If Codex needs accurate context-window or reasoning metadata for a custom Qwen model, Alibaba's guide provides a `model-catalog.local.json` pattern and the `model_catalog_json` setting. Copy the current metadata from Alibaba's maintained page instead of inventing token limits or capability flags.
For a team, distribute a reviewed `config.toml` template without credentials. Keep each key's owner, workspace, region, model permission, IP policy, rotation date, and revocation status in the credential system you choose later. The technical config and the key-distribution policy are separate documents.
FAQ
Should I put the Alibaba key directly in config.toml?
No. Set `env_key` to the name of an environment variable and keep the credential in an approved secret store or process environment.
Can I use OPENAI_API_KEY instead of DASHSCOPE_API_KEY?
Technically yes if `env_key` matches, but a dedicated name is safer and prevents confusion when OpenAI and Alibaba credentials coexist.
Which Alibaba model should I use with current Codex?
Choose a model Alibaba currently documents as supporting the Responses API and that your workspace permits. This guide uses `qwen3.7-max` as the documented example.
Can I use a model that only supports Chat Completions?
Not with the current recommended Codex route. Modern Codex requires the Responses API; use a Responses-capable model instead of relying on an old client downgrade.
Why does the API Host contain a workspace ID?
Alibaba ties ordinary API keys and access controls to a workspace and region. The workspace host ensures the request reaches the matching resource boundary.
A dependable Alibaba-to-Codex setup has five matched parts: an ordinary Model Studio key, its workspace API Host, the same region, a permitted Responses-capable model, and a local Codex custom provider that reads the key from the environment. Verify that exact path before expanding it into a distribution workflow.
Related model comparisons
Continue from this guide into structured DeepSeek-first comparison pages with model tables, routing advice, and pricing context.