ZCode Custom Models: Claude & GPT

ZCode is Zhipu's desktop coding agent; point it at Code By AI to run Claude and GPT models through one OpenAI-compatible provider.

ZCode is an Agentic Development Environment, not a terminal wrapper: the agent drives files, the terminal, Git and a browser preview from a chat session. Its Model Settings panel accepts custom providers, so only the model connection changes; the agent and UI stay as they are.

One command (macOS / Linux)

Quit ZCode first. It keeps its provider registry in memory and rewrites ~/.zcode/v2/config.json when it saves or exits, which would discard edits made while it runs.

Copy
1
curl -fsSL https://www.codebyai.net/setup.sh | sh -s -- --zcode

The script asks for your API key (hidden input), adds a codebyai provider with gpt-5.6-terra and claude-sonnet-5, backs up the file, and leaves it owner-only. Re-running it rotates the key; | sh -s -- --uninstall restores the file it found. The manual steps below do the same by hand.

1. Create a Code By AI API key

Sign in to Code By AI, open API Keys, and create a key. It looks like sk-proj-....

2. Open the model settings

In ZCode, open the model selector at the bottom of the chat box and click Manage models. That opens Settings → Model Settings, where providers are added.

3. Add the provider

1. Click Add Provider at the bottom of the provider list on the left.
2. Name it Code By AI.
3. Set the OpenAI API base URL to https://www.codebyai.net/api/agent/v1.
4. Paste the Code By AI API key.
5. Save, then click Add Model and enter gpt-5.6-terra. Click Add Model again for claude-sonnet-5.
6. Turn on the provider's enable switch.

Use the OpenAI protocol for both families. ZCode's Anthropic-messages mode sends a legacy thinking parameter that current Claude models reject; the gateway's Chat Completions route forwards claude-* IDs to the Claude channel and bills them at Claude prices, so one provider covers both.

4. Select the model and test

Open a session, pick either model from the model selector, and ask a short question. A normal reply confirms that the endpoint, key and model ID all agree.

Model IDs and context windows

Use the IDs listed on the Model Plaza; the two above are the examples this guide was written with. A model added to a custom provider starts with a 200,000-token context window in ZCode. Open the model under Settings → Model Providers → Advanced to change that value and the maximum output tokens. Both settings apply to new sessions after you save.

Troubleshooting

• 404 page not found — the base URL is incomplete or carries an extra path. Use https://www.codebyai.net/api/agent/v1; do not append /chat/completions, and do not add a second /v1.
• 401 / invalid key — the key has stray spaces, was deleted, or expired. Create a new key on the API Keys page and paste it again.
• Insufficient balance — top up on the Wallet page.
• 400 mentioning a reasoning level — a custom provider can reject the highest thinking-effort level ZCode offers. Lower the effort for that model; the gateway forwards the level ZCode sends.
• The provider's model list is empty — the enable switch is off, or Add Model was never saved.
• The provider disappears after restarting ZCode — the app was still running when the script wrote the file. Quit it completely, run the command again, then reopen it.