ZCode AI Custom API Setup

ZCode can add services that implement the Anthropic or OpenAI protocol as Custom Providers. This guide follows the actual order in ZCode's official Connect Models → Custom Providers (Anthropic / OpenAI Compatible) flow and configures TokenHub as an OpenAI-compatible provider at https://us-api.tokenhub.com/v1.

Open model settings

On first launch, when no model is available, select Use API Key. If ZCode is already open, click the model name in the prompt box, choose Manage Models, and open Settings → Model Settings.

Add the TokenHub Custom Provider

Follow the seven steps in ZCode's Custom Provider flow:

1. Open Settings → Model Settings.
2. At the bottom of the provider list, click Add Provider.
3. Name the provider TokenHub.
4. Choose OpenAI-compatible. In the Base URL menu, select a custom address or enter https://us-api.tokenhub.com/v1 manually.
5. Enter your TokenHub API key in API Key.
6. Click Add Model and enter an exact model ID from the TokenHub model catalog. Add each additional model separately.
7. Save the settings and turn on the provider's Enable switch. Confirm that every model you intend to use is enabled as well.

ZCode does not infer third-party model IDs for you. If the provider does not return a model list, add each exact ID manually with Add Model.

Do not mix Anthropic and OpenAI protocol settings in one provider. Create a separate provider for Anthropic Messages and use the root URL required by that protocol.

Configure Advanced settings for one model

Under Settings → Model Providers, open the model you added and expand Advanced:

• Max output tokens: normally leave this empty and let the model service report the supported value. Set it manually only after confirming the target model's limit.
• Context window: this is editable for Custom Provider models and the saved value applies only to new conversations. Use the TokenHub model specification, not the value from another model.
• Thinking effort: visible levels depend on the model and protocol. OpenAI-compatible requests use reasoning_effort; a third-party deployment may reject some levels shown by ZCode. Lower the level or disable the option after a 400 parameter error.
• Custom request parameters: ZCode does not automatically inject arbitrary values manually added to local provider options into the request body. Do not rely on editing ~/.zcode/v2/config.json to add extra reasoning or image parameters.

How ZCode decides whether image input is available

ZCode combines the provider, model ID, model-catalog capabilities, and active protocol when handling images:

• When support is known, ZCode keeps the image and sends it to the model service.
• When the model is marked unsupported, ZCode removes the image and substitutes a text notice.
• When capability is unknown, ZCode does not block the image in advance; TokenHub makes the final decision and may reject the request.

The same model can be treated differently through another provider or protocol. Test text first, and send an image only when the TokenHub model page explicitly lists image input.

Select the model and verify

1. Return to the model selector in the prompt box.
2. Choose the TokenHub provider and the model you added.
3. Send a short instruction such as “Explain the current file without modifying it.”
4. In TokenHub request logs, confirm that the request uses /v1/chat/completions, and verify the model ID, status code, and usage.
5. After text responses are stable, test editing, tool calls, long context, and image input separately.

This follows ZCode's official Verify The Setup guidance: select the new channel, send a short test instruction, and confirm a stable response before real work.

Scope of ZCode's built-in HTTP proxy

An HTTP Proxy configured in ZCode Settings covers model APIs, MCP, WebFetch, terminal child processes, the extension marketplace, and in-app page loading. It does not cover desktop account sign-in, Wiki generation, the Web Remote Control WebSocket, or SSH remote connections. ZCode also does not route every request through system HTTP_PROXY / HTTPS_PROXY variables by default. Restart ZCode after changing the in-app proxy.

Troubleshooting

• Model missing: make sure both the provider and the model are enabled.
• 404: confirm the endpoint does not repeat /chat/completions.
• Request-format mismatch: check whether the provider is OpenAI-compatible or Anthropic.
• Text works but code editing does not: the selected model may not have reliable native tool calling.
• Thinking effort returns 400: lower or disable the level because the deployment may not accept it.
• Image request fails: use a canonical model ID and confirm the provider, protocol, and TokenHub model all support images.
• Proxy change has no effect: restart ZCode and confirm that the traffic type is covered by ZCode's built-in proxy.

Official reference

• ZCode: Connect Models