oc-zai-multi-account

Never hit a Z.AI rate limit again — multi-account key rotation and automatic failover for OpenCode's zai-coding-plan provider.

Spread requests across multiple Z.AI / ZhipuAI Coding Plan API keys. When a request fails with 429, 401, or 5xx, the plugin switches to the next key and retries once. You keep the normal OpenCode GLM model list (glm-5, glm-5.1, glm-4.7, etc.) while the plugin handles key management behind the scenes.

Tested with OpenCode 1.4.3 and Node.js 20+.

What this plugin does

• targets zai-coding-plan only
• reuses OpenCode's built-in GLM model registry
• injects Authorization: Bearer <key> at request time
• loads keys from ~/.config/opencode/zai-keys.json or ZAI_API_KEYS
• rotates to the next key on 429, 401, or 5xx
• sets model cost to zero in memory so Coding Plan usage does not show token pricing

What this plugin does not do

• it does not add support for the general zai provider
• it does not fetch models dynamically from Z.AI
• it does not define custom models in the plugin
• it does not persist runtime cooldown/disable state across process restarts

How it works

OpenCode already knows the zai-coding-plan provider and its GLM models. This plugin does not replace that provider. Instead, it hooks into OpenCode's auth.loader for zai-coding-plan and swaps in a custom fetch implementation that chooses the active key, injects the Bearer token, and retries once with the next key when needed.

At runtime, the key source priority is:

1. ZAI_API_KEYS
2. ~/.config/opencode/zai-keys.json
3. the single API key stored in OpenCode auth for zai-coding-plan

Requirements

• Node.js 20+
• OpenCode with plugin support
• access to Z.AI Coding Plan keys

Installation

Option 1: npm package

Add the plugin to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["oc-zai-multi-account@latest"]
}

Option 2: local path

Clone the repository, build it, then reference the compiled file:

npm install
npm run build

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["/absolute/path/to/oc-zai-multi-account/dist/index.js"]
}

For local-path usage, dist/ must exist. Build first.

OpenCode configuration

This plugin depends on the built-in zai-coding-plan provider, so keep a minimal provider stub in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["oc-zai-multi-account@latest"],
  "provider": {
    "zai-coding-plan": {
      "options": {
        "apiKey": "oc-zai-multi-account-managed"
      }
    }
  }
}

Why the provider stub is required

OpenCode only exposes models for providers that are active in config/auth state. Without a zai-coding-plan provider entry, the GLM models may not appear in the model list even though the plugin is installed.

The apiKey value above is only a bootstrap placeholder. The plugin replaces it at request time with a real key from your configured key sources.

Configure your keys

Recommended: ~/.config/opencode/zai-keys.json

{
  "keys": [
    {
      "id": "main",
      "label": "Main",
      "apiKey": "sk-xxx",
      "enabled": true
    },
    {
      "id": "backup",
      "label": "Backup",
      "apiKey": "sk-yyy",
      "enabled": true
    }
  ],
  "rotation": {
    "strategy": "round-robin",
    "cooldownMs": 60000
  }
}

Alternative: environment variables

export ZAI_API_KEYS="sk-xxx,sk-yyy,sk-zzz"
export ZAI_ROTATION_STRATEGY="round-robin"
export ZAI_COOLDOWN_MS="60000"

If neither the file nor environment variables are set, the plugin falls back to the single API key stored in OpenCode auth.

One-time auth bootstrap

After installing the plugin and adding the provider stub, create an auth record for zai-coding-plan once:

opencode providers login \
  --provider zai-coding-plan \
  --method "Z.AI Coding Plan API Key"

When prompted, enter:

oc-zai-multi-account-managed

This placeholder is intentional. It activates the provider/auth path inside OpenCode so the plugin's auth.loader can take over and inject the real keys from zai-keys.json or ZAI_API_KEYS.

If you want to use OpenCode auth as the only key source instead of zai-keys.json / ZAI_API_KEYS, enter your real Z.AI Coding Plan key here instead of the placeholder.

If you skip this step, you may see one of these symptoms:

• zai-coding-plan models do not appear
• requests fail before the plugin's rotating fetch runs
• token expired or incorrect even though your key file is valid

Migration from custom zai1 / zai2 providers

If you previously configured multiple custom Z.AI providers in opencode.json, remove them once this plugin is enabled.

Delete blocks like:

"provider": {
  "zai1": { ... },
  "zai2": { ... }
}

and keep only the single zai-coding-plan provider stub shown above.

Runtime behavior

For requests to zai-coding-plan:

1. the plugin selects the next available key
2. it sends Authorization: Bearer <key>
3. if the response is:
   • 2xx: success, keep going
   • 429: put the current key into cooldown, try the next key once
   • 401: disable the current key for the rest of the process, try the next key once
   • 5xx: try the next key once
4. if all enabled keys are cooling down, wait for the shortest cooldown to expire
5. if the retry also fails, return the original error to OpenCode

Current implementation details:

• retry count: 1
• rotation strategy: round-robin
• default cooldown: 60000ms
• state is in memory only

Models

This plugin does not define any models. It relies on OpenCode's built-in zai-coding-plan provider and its built-in GLM model list.

That means you keep the standard model IDs exposed by OpenCode, such as:

• glm-5
• glm-5.1
• glm-5-turbo
• glm-4.7
• glm-4.7-flash
• glm-4.7-flashx
• glm-4.6
• glm-4.5

and the rest of the zai-coding-plan models bundled by your OpenCode version.

Usage checks

After setup, these commands are useful:

opencode providers list
opencode models zai-coding-plan

You should see:

• a Z.AI Coding Plan credential entry
• the normal GLM model list for zai-coding-plan

Troubleshooting

GLM models are missing

Check all three conditions:

1. the plugin is installed and loaded
2. provider.zai-coding-plan exists in opencode.json
3. you completed the one-time auth bootstrap with opencode providers login

token expired or incorrect

Usually this means one of these:

1. the auth bootstrap step was skipped, so OpenCode never entered the plugin auth path
2. the keys in zai-keys.json or ZAI_API_KEYS are invalid
3. the plugin is not loading from the path/package you expect

Recommended checks:

opencode providers list
opencode models zai-coding-plan

Then verify that:

• ~/.config/opencode/zai-keys.json exists and contains real keys
• opencode.json still contains the zai-coding-plan provider stub
• your plugin entry points to the built dist/index.js

Local-path plugin is installed but does nothing

Make sure you built the plugin:

npm install
npm run build

and confirm the path points to dist/index.js, not src/index.ts.

I want to use only one key

That works too. Configure one key in zai-keys.json or rely on the OpenCode auth fallback. You just will not get any failover benefits.

Security notes

• never commit real API keys
• keep ~/.config/opencode/zai-keys.json outside your repository
• do not publish zai-keys.json, .zai_api_key_*, or screenshots containing provider credentials
• if you are migrating from old zai1 / zai2 config, remove stale key files you no longer use

Development

npm install
npm run check
npm run build

License

MIT