Cherry Studio with AIXHUB

Use this guide to add AIXHUB as a custom OpenAI provider in Cherry Studio. The workflow separates the provider's built-in check from the first real chat and from AIXHUB Usage verification.

What you will accomplish

By the end of this guide, you will have:

1. Installed an official Cherry Studio build for your platform and processor architecture.
2. Recorded or backed up the original provider state without exposing stored keys.
3. Added an enabled AIXHUB provider with one exact panel-model-id model.
4. Run the provider Check action with the intended model.
5. Completed a tool-free chat that returns OK and matched it in AIXHUB Usage.
6. Kept a field-level restore plan that preserves later chats, assistants, and settings.

Supported platforms

Cherry Studio publishes packages for:

• Windows: x64 and ARM64.
• macOS: Intel and Apple Silicon.
• Linux: x86_64 and ARM64 AppImage.

Choose the package that matches the operating system and processor. Package names, versions, and direct download URLs can change, so use the official download page or GitHub releases instead of copying an old direct link.

Install or open the app

Download Cherry Studio from the official download page or GitHub releases. Do not rely on a version number embedded in a third-party tutorial.

Install or open the package for the correct architecture. If the app displays its current version, record it with your configuration notes, but do not depend on a particular About menu label. Complete any operating-system trust or installation prompt only after confirming the package came from the official channel.

Configuration values

The API address is a Base URL. Current Cherry Studio behavior appends /v1 when an API Host has no version, while https://api.aixhub.org/v1 remains unchanged before the client appends /chat/completions. This means https://api.aixhub.org can also be normalized to the versioned base. This guide recommends the explicit https://api.aixhub.org/v1 value so it can be compared directly with the AIXHUB Base URL. Never paste a full /v1/chat/completions or /v1/responses endpoint into this field. If an error shows /v1/v1, inspect the active field and version composition, then return to the explicit recommended value and compare it with the current Cherry Studio provider documentation.

Configure AIXHUB

Back up and record the original state

1. Open the settings gear in the left sidebar, then open Data Settings.
2. If the installed version provides local or cloud backup, create one controlled backup before editing providers. Use only storage and a synchronization account you trust and are authorized to use.
3. Treat the backup as a credential file: a complete data backup includes provider configuration and API keys. Do not share it, attach it to a support ticket, or upload it to untrusted storage.
4. Record whether an AIXHUB provider already exists. Record its non-secret fields, model list, enabled state, and whether its key belongs to another setup. Keep any exact secret value only in the protected backup, not in an ordinary note.

If backup is unavailable, make a protected field-level record. If the provider's original ownership or state is unknown, stop instead of assuming it can be overwritten or deleted later.

Add the custom provider

1. Select the settings gear, then open Model Services.
2. At the bottom of the provider list, choose + Add.
3. Enter AIXHUB as the provider name, select OpenAI as the provider type, and add it.
4. Find the new AIXHUB provider in the provider list.

If AIXHUB already existed, compare it with the protected record and decide explicitly whether replacing its fields is intended. Do not create duplicate providers with slightly different names.

Enter the key and API address

1. Create or select a dedicated AIXHUB API key for Cherry Studio.
2. Enter it in the provider's API Key field without displaying it elsewhere.
3. Set the API address to exactly https://api.aixhub.org/v1.

Do not paste the key into a prompt, provider name, model field, or official-account login flow.

Add the model and enable the provider

1. Choose + Add in the model area and enter the exact panel-model-id from Model routes.
2. When the model-management dialog displays a list, click the + control at the right of panel-model-id. Seeing a model in the dialog is not enough; the right-side + action actually adds it to the provider.
3. Return to the provider and confirm panel-model-id appears in its added model list.
4. Turn on the enable switch at the provider's right side or upper-right area.

The provider or model can remain invisible in chat until both the model is actually added and the provider is enabled.

Run the provider check

Click Check to the right of the API Key field. The check uses the last conversation model in the provider's added model list by default. Before running it, make sure panel-model-id is the last intended conversation model, and remove a mistaken trailing model when necessary.

A successful check confirms that Cherry Studio can make a provider request with that selected model. It is not final proof that a later chat used AIXHUB; the first chat and Usage record still need separate verification. The check sends a real request and may produce a small amount of usage.

First run

Create a new chat or assistant. Explicitly select the AIXHUB provider and panel-model-id for that conversation instead of relying on an old assistant default or fallback.

For the first request, do not enable web access, MCP, a knowledge base, tools, or automatic fallback. Send:

Do not use tools or change any data. Reply with OK only.

Wait for the response before enabling any additional capability.

Verification

The provider check should succeed, and the new chat should return:

OK

Then open AIXHUB Usage and match the chat request time, panel-model-id, and successful status. If Usage displays a protocol or API mode, compare it with the selected provider type; do not assume that field is always visible. Confirm that the chat still shows AIXHUB and panel-model-id after reopening it.

Troubleshooting

The provider or model is missing

Confirm that the provider's enable switch is on. Reopen model management and verify that you clicked the + control at the right of panel-model-id; merely seeing it in the available list does not add it. Return to chat and select the provider and model again.

Check fails or uses the wrong model

The check uses the last conversation model in the provider's added model list. Make panel-model-id the last intended conversation model or remove an incorrect trailing entry, then retry. A check failure does not by itself prove the API Key or Base URL is wrong.

401 or authentication failed

Confirm that the API Key field contains a current dedicated AIXHUB key and that the enabled AIXHUB provider is being checked. Do not use an AIXHUB dashboard password or an official OpenAI credential. Re-enter the key without showing it in screenshots or logs.

404, a doubled API version, or an endpoint error

Use the explicit recommended API address https://api.aixhub.org/v1. Current Cherry Studio can also accept https://api.aixhub.org and append /v1 itself, so the root address alone is not necessarily the cause of a 404. Remove full endpoint suffixes such as /v1/chat/completions or /v1/responses from the Base URL field. If /v1/v1 appears, inspect the active provider field and any imported settings, then restore the explicit recommended Base URL.

model not found

Copy the complete model ID again from Model routes, remove the incorrect model entry, and add panel-model-id through the right-side + control. Check that the selected route supports the OpenAI-compatible request used by Cherry Studio.

Chat succeeds but Usage has no matching record

The conversation may be using another provider, an assistant default, or fallback. Open that chat's model selector, explicitly choose AIXHUB and panel-model-id, disable fallback for the test when available, and retry. Match time, model, and status rather than treating the visible response as route proof.

Proxy or network failure

Check Cherry Studio's active network or proxy settings and the operating system's connectivity. Keep HTTPS certificate validation enabled. Distinguish a local connection failure from an AIXHUB HTTP error before changing provider fields.

For 403, 429, 502, or 503 responses, continue with the error code reference.

Upgrade and restore

Before upgrading, create a new controlled backup through Data Settings and record the provider fields, model list, enabled state, and backup location. Upgrade only through the official download page or GitHub releases, then repeat the provider check, tool-free chat, and Usage verification.

If AIXHUB was originally absent, delete the new provider only after confirming that no later chat, assistant, default, fallback, or other setting depends on it and that its fields still match this guide's addition. If AIXHUB already existed, restore its exact original fields, model list, enabled state, and key ownership; do not delete it.

Restore a complete data backup only during a controlled window when doing so will not overwrite later chats, assistants, provider changes, or other settings that must be kept. Otherwise perform a field-level restore and preserve later unrelated state. If ownership or original state is unknown, stop rather than guessing.

Revoke or rotate the dedicated key when the restored configuration no longer needs it. If the key remains in use elsewhere, verify its ownership before changing it.

Security

• Use a dedicated AIXHUB key for Cherry Studio so it can be rotated independently.
• Treat every full data backup as a sensitive credential file because it includes provider API keys.
• Restrict access to the local device, backup location, and any synchronization account that stores Cherry Studio data.
• Never paste the key into a prompt, commit it, or include it in screenshots, exported logs, diagnostics, and support messages.
• Rotate the key immediately after exposure, then update the protected provider field and reverify the chat.
• The Check button sends a real request and may create a small Usage record; do not repeatedly click it without need.

Official sources

• Custom provider
• Provider settings
• Data settings
• Download Cherry Studio

Last verified: 2026-07-14