Generic OpenAI-compatible clients

Use this guide when a GUI or command-line client supports a custom provider or an OpenAI-compatible API but does not have a dedicated AIXHUB tutorial. An AIXHUB API key is not an official OpenAI sign-in credential: always use the client's custom Provider, custom API, or OpenAI-compatible setup flow.

Prerequisites

• Create a dedicated AIXHUB API key for this client. Keep it in the client's secret field or documented secret store; do not display it in a terminal.
• Copy the exact compatible model ID from Model routes. This guide uses panel-model-id wherever a model is required.
• Confirm that the client supports a custom Base URL. Official-account login alone is not enough.
• Identify whether the client expects an OpenAI-compatible API, and whether it offers OpenAI Responses mode.
• Back up the current client configuration or record the exact provider, URL, model, API mode, and credential-storage choice before changing anything.

If the tool cannot set a custom provider and Base URL, stop. Do not paste the AIXHUB key into an official OpenAI, Google, Anthropic, or other vendor login form.

Steps

Choose the custom provider flow

In a GUI, look for a path such as Settings → Providers → Add custom provider or OpenAI-compatible. In a CLI, use its documented custom-provider configuration file or flags. Names vary by client, but the flow must expose a custom URL and API key field.

Do not select an official-account sign-in flow. If the client forces browser login and offers no custom API fields, it cannot use this generic setup.

Enter the core fields

Use these values:

Copy the model ID rather than typing it from memory. Do not expose the key in a screenshot, command output, or support log.

Match the URL to the field meaning

The label determines which URL is correct:

Most clients ask for a Base URL, so start with https://api.aixhub.org/v1. Use the root URL only when the client documentation explicitly says it appends /v1. Use the full endpoint only in a field that explicitly requests an endpoint.

Never produce /v1/v1. Do not place https://api.aixhub.org/v1/responses in a Base URL field, because the client may append the request path again.

Save, restart, and select the route

Save the custom provider, then fully close and reopen the GUI or CLI so it reloads the key, URL, model, and mode. Confirm that the active provider is AIXHUB and the active model is panel-model-id. If the client has separate chat, agent, and default-model settings, verify the one used by the test session.

Send a small request before enabling tools or starting a larger task:

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

After the response, open AIXHUB Usage. Match the request time and panel-model-id to the test, and confirm that the recorded status is successful. If Usage displays a protocol or API mode for the request, compare it with the client selection. If it does not, use the API mode selected in the client together with the successful AIXHUB request as the configuration evidence; do not claim that Usage always exposes a protocol field. A response by itself does not prove that the client used AIXHUB.

Back up and restore

Before editing, record the exact original provider, Base URL or endpoint, model, API mode, and credential-storage selection. If the client exports settings, protect the export because it may contain secrets.

To restore, fully close the client and put back each recorded original value. Restore an original provider object or profile rather than deleting it. Remove an AIXHUB-only entry only when the record confirms that entry did not exist before this guide. If the original state is unknown, stop and recover a trusted copy instead of guessing.

Security checklist

• Use a dedicated AIXHUB key for this client so it can be rotated or revoked independently.
• Keep the key in a secret field, operating-system keychain, or the client's documented secret mechanism.
• Never commit the key, paste it into a prompt, display it with an echo command, or include it in screenshots and support logs.
• Review imported profiles and project-level settings because they can replace the provider, URL, or model.
• Rotate the key immediately if it is exposed, then update only this client's protected credential.

Verification

The client should return this exact output for the bounded request:

OK

In AIXHUB Usage, confirm a successful request at the same time with panel-model-id. Only compare the protocol or API mode when Usage actually displays that field; otherwise, rely on the mode selected in the client and the successful matching request without attributing an unavailable field to Usage. Also confirm that the active provider still reads AIXHUB after a full restart.

Troubleshooting

No custom provider option

Update the client and check its current documentation for custom API, custom provider, or OpenAI-compatible support. If it only offers official account login, do not enter an AIXHUB key. Choose a dedicated guide or another client that supports a custom Base URL.

401 or authentication failed

Confirm that the secret field contains the current dedicated AIXHUB key and that the custom AIXHUB provider is active. Do not substitute an AIXHUB dashboard password or complete an official OpenAI login to hide a missing custom credential. Re-enter the key without displaying it, then fully restart the client.

404, endpoint not found, or doubled API version

Check the field meaning. Base URL or API Base usually needs https://api.aixhub.org/v1; Host or Origin uses https://api.aixhub.org only when the client appends the version; Full endpoint for Responses uses https://api.aixhub.org/v1/responses. Remove duplicate paths such as /v1/v1 and never put the full endpoint in a Base URL field.

model not found

Copy the exact model ID again from Model routes. Keep panel-model-id unchanged unless the panel shows a different complete ID. Confirm that the selected model supports the API mode chosen by the client.

The request succeeds but Usage has no matching record

The client probably used another provider, official account, fallback, or session-level model. Recheck the active provider, model, and protocol after restarting. Disable automatic fallback for the small verification request when the client allows it, then repeat the test and match its time in Usage.

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

Next step

• Before connecting code, create another dedicated AIXHUB key used only by that code; do not reuse this client's key. Then review API authentication.
• Use Claude Code for its Anthropic-compatible environment-variable flow.
• Use Codex CLI for its Responses provider and separate credential file.
• Use OpenCode for its opencode.json provider format.
• Use OpenClaw for its model-provider and local agent flow.

General references

• AIXHUB API authentication
• AIXHUB OpenAI Responses
• AIXHUB Usage records

Last verified: 2026-07-14