Feature: managed ZCode (Z.ai desktop client) integration — ocx zcode sync #2022

Area

CLI

What are you trying to accomplish?

I want to use ZCode (Z.ai's desktop coding client, https://zcode.z.ai) with all the providers OpenCodex already routes, the same way ocx claude, ocx opencode, and ocx mcode wire their respective clients to the local proxy. ZCode supports Anthropic-protocol custom providers, and OpenCodex already serves an Anthropic-compatible /v1/messages endpoint, so ZCode should be able to consume the full OpenCodex catalog (Kimi, Grok, GLM, DeepSeek, etc.) through one loopback provider entry.

What prevents this today?

There is no ocx zcode integration. ZCode stores custom providers in ~/.zcode/v2/config.json (a provider map with kind, options.baseURL, options.apiKey, and a per-model models object including limit.context). Today a user has to hand-write that block, hand-copy the proxy admission key, hand-enter every model ID with correct casing, and hand-update context limits whenever the catalog changes. ZCode also requires a restart/new session to pick up provider changes, so a stale hand-written block silently drifts from the live catalog.

What should OpenCodex do?

Provide a managed ZCode integration, following the existing managed client-config precedent (ocx mcode / ocx opencode):

• ocx zcode sync (or equivalent) writes a single managed opencodex provider entry into ~/.zcode/v2/config.json: kind: "anthropic", baseURL pointing at the live loopback proxy, and models generated from the proxy catalog with authoritative limit.context values.
• The write must be a merge that preserves every existing user provider (including Z.ai OAuth/coding-plan entries and their credentials) byte-for-byte; only the managed key is added or updated.
• Removing the integration removes only the managed key.
• The admission key handling must not leak into logs or test fixtures (privacy:scan stays green).

Example usage or interface

# one-time: write/refresh the managed provider block from the live catalog
ocx zcode sync

# result in ~/.zcode/v2/config.json (user entries untouched):
# "opencodex": {
#   "name": "OpenCodex Proxy",
#   "kind": "anthropic",
#   "options": { "apiKey": "<admission key>", "baseURL": "http://127.0.0.1:10100", "apiKeyRequired": true },
#   "enabled": true,
#   "source": "custom",
#   "models": { "kimi/kimi-k2.5": { "limit": { "context": 262144 } }, ... }
# }

After a ZCode restart, the OpenCodex provider appears in Model Settings and chats route through the proxy.

Alternatives or workarounds

Hand-editing ~/.zcode/v2/config.json works (validated manually against the running proxy) but is fragile: model IDs are case-sensitive, context limits drift from the catalog, the admission key must be copied manually, and every catalog change requires another hand edit plus restart.

Additional context

• ZCode custom-provider docs: https://zcode.z.ai/en/docs/configuration (Anthropic/OpenAI protocol custom providers; restart required after provider changes).
• Closest in-repo precedent: src/cli/minimax.ts (ocx mcode managed custom_provider.opencodex block) and src/clients/config-export.ts (shared client-config export surface).
• The proxy side needs no changes: /v1/messages already serves Anthropic-protocol clients (Claude Code path).

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.