Cherry Studio OpenAI-Compatible Provider Configuration: A Step-by-Step Guide

Configuring Cherry Studio with a custom OpenAI-compatible provider is a four-field setup that can be completed in minutes. It gives you one unified gateway to multiple model families through a single API key and base URL — the most flexible option when Cherry Studio's built-in provider list does not cover your preferred aggregator. As of September 2026, Cherry Studio's official repository still lists "OpenAI-Compatible" as a selectable custom provider type (Cherry Studio GitHub). If you use HeFu, confirm the Base URL and model IDs through its official console and documentation rather than third-party blogs: the developer API base URL is https://api.hefu.hk/v1, and the authoritative model directory is the HeFu model catalog.

Why Configure an OpenAI-Compatible Provider in Cherry Studio?

Cherry Studio is an open-source desktop AI assistant client. Its official README states support for Windows, macOS, and Linux (Cherry Studio README). As of September 2026, the number of built-in providers changes with each release; check the providers configuration and release notes in the official repository. Whether maintainers will add more aggregator-type providers is a roadmap item that should also be verified against official issues and documentation.

An OpenAI-compatible interface typically requires a JSON request with model and messages fields sent to POST /v1/chat/completions, with a response format matching the OpenAI Chat Completions API (OpenAI API Reference). Through one OpenAI-compatible endpoint, you can centralize authentication, billing, and rate limiting instead of maintaining separate API keys for every model vendor. This pattern applies to clients that support custom OpenAI-compatible providers — Cherry Studio, Cline, and Cursor among them — without modifying the upstream interface for each client.

Prerequisites: What You Need Before Starting

Before opening Cherry Studio's settings, confirm the following:

1. An account with a valid API key from your service provider; generate the key in the provider's official console, not through third-party resellers or reposted keys.
2. A current release of the Cherry Studio desktop client is installed and running; check Cherry Studio Releases for the version status.
3. Your network can reach the provider's Base URL reliably. Whether you need a proxy, custom DNS, or overseas payment depends on the provider's operating entity and cannot be generalized — follow the provider's official documentation.
4. Copy the model IDs you plan to use from the provider's official model catalog; a custom OpenAI-compatible provider generally does not sync the remote model list automatically.

Obtaining Your HeFu API Key and Base URL

Using the OpenAI-compatible flow as a general example: log in to your provider's console and generate a key on the API Key management page (for HeFu, create an account here). The Base URL is the API root address provided by the service, usually ending in /v1. For HeFu, the developer API base URL is https://api.hefu.hk/v1, as documented on the HeFu developer docs. For comparison, OpenAI's official API root is https://api.openai.com/v1 (OpenAI API Overview). When pasting into Cherry Studio, keep the string exact: the trailing /v1 must be present, and do not append full paths such as /chat/completions.

As of September 2026, model IDs are provider-specific fields; only the provider's official model catalog is authoritative. Model names from third-party blogs may include IDs that are deprecated, renamed, or not yet released, so always check the official catalog. For HeFu, the authoritative directory is the HeFu model catalog; model names quoted from any other source should not be used as configuration references.

Adding a Custom OpenAI-Compatible Provider in Cherry Studio

The configuration flow is short: in Cherry Studio, go to Settings → Model Service → Add, select the custom OpenAI-compatible provider, and fill in four fields:

• Name — any label, e.g., "My Gateway"
• Type — OpenAI-compatible
• API Key — your provider key
• Base URL — the provider's root address, e.g., https://api.hefu.hk/v1

As of September 2026, Cherry Studio's official UI still uses this four-field flow; the exact interface text depends on the version you have installed (Cherry Studio GitHub). If you have already configured an OpenAI-compatible provider in Cline or Cursor, the field semantics in Cherry Studio are essentially the same.

On the endpoint side: OpenAI officially provides both the Chat Completions API and the Responses API (OpenAI API Reference). However, "OpenAI-compatible" generally refers to services implementing /v1/chat/completions; unless the provider explicitly documents support for /v1/responses, ensure requests actually land on /v1/chat/completions. Claims that newer Cherry Studio versions automatically detect /v1/responses have no official source support; rely on your installed version's behavior and the provider's documentation.

Selecting Models from the Official Model Catalog

After adding the provider, Cherry Studio usually shows an empty model list under the custom provider, and you must add model IDs manually. Copy the complete ID from the provider's official model catalog. The following are only naming-format examples from each vendor's documentation — they do not mean the IDs are necessarily available through any given gateway, and they are not a purchase list for HeFu:

• OpenAI GPT series: official model IDs have appeared in formats such as gpt-4o and gpt-4-turbo (OpenAI Models)
• Claude series: Anthropic official model IDs have appeared in formats such as claude-3-5-sonnet (Anthropic Models)
• DeepSeek: official API documentation has used deepseek-chat as a model ID example (DeepSeek API Docs)
• Kimi / Moonshot: Moonshot's official API documentation uses kimi-* series IDs (Moonshot Docs)
• Gemini: Google's API model IDs are written in gemini-* format (Google AI Developer Docs)
• Other Chinese-origin models: Qwen, GLM, Doubao, and others follow each vendor's official API documentation

For models actually available through HeFu, always use the HeFu model catalog, which covers the GPT-5.x family, Claude Opus/Sonnet series, DeepSeek reasoning models, Kimi long-context models, Gemini multimodal models, and Chinese-origin models such as Qwen and GLM. Paste each ID into Cherry Studio's model list and verify that the current API key's account has access to that model. If you get "model not found," the most likely causes are an incomplete ID or an outdated one — re-check the official catalog.

The following table compares common connection methods:

Connection Method	Setup Cost	Endpoint Compatibility	Typical Use Case
Built-in provider (count varies by release; see official docs)	Select from list, then enter vendor key	Vendor-specific; some use native endpoints	Quick connection to a single official vendor
Custom OpenAI-compatible (recommended)	Manually fill in 4 fields	/v1/chat/completions is the standard OpenAI-compatible endpoint	Access multiple model families through one aggregator gateway
Custom Anthropic protocol	Requires Anthropic-format key (sk-ant-...)	Claude native endpoint	Claude-only use without an aggregation layer
Local HTTP (Ollama / LM Studio)	Point to a localhost URL	Depends on the local service implementation	Offline or private model experiments

Testing and Verifying Your Configuration

After adding the provider and models, send a short message in Cherry Studio and check the connection logs to confirm:

• The request reaches the provider's Base URL and returns HTTP 200.
• The model name in the response matches expectations.
• If streaming is enabled, the SSE stream terminates normally.

HTTP status codes are the first diagnostic clue: 401 means authentication failed, commonly an invalid or incorrectly formatted API key; 404 means the request path or model ID does not exist; 400 means the request parameters do not conform to the /chat/completions specification (OpenAI Error Guide).

Troubleshooting Common Configuration Issues

• 401 Unauthorized — Almost always a key format or key ownership problem. Anthropic native keys start with sk-ant- and cannot be entered into OpenAI-compatible fields (Anthropic Authentication). A unified aggregator gateway that uses a single key format avoids this issue.
• Incorrect Base URL string — Use the root address, e.g., https://api.hefu.hk/v1. If you paste the full https://api.hefu.hk/v1/chat/completions, the client may append its own path and create a doubled path that breaks routing.
• Empty model list — A custom OpenAI-compatible provider does not automatically sync the remote model directory; add official model IDs manually from the HeFu model catalog.
• Silently ignored parameters — OpenAI reasoning models use snake_case parameters such as reasoning_effort (OpenAI Reasoning Guide). Some clients or SDKs rewrite parameters before transmission, so the upstream may receive undefined; verify against the provider's logs.
• Firewall or proxy restrictions — If requests time out, confirm the client process's network can reach the provider's Base URL directly and that any corporate proxy is not blocking or rewriting HTTPS requests.

Best Practices for Security and Reliability

Treat your API key like a password: do not write it into shared configuration files, do not commit it to a Git repository, and prefer environment variables or OS keychain storage. GitHub's documentation recommends mechanisms such as Secret Scanning to keep plaintext keys out of codebases (GitHub Docs). When team members share an account, use sub-keys with least-privilege permissions and independent metering that can be revoked individually from the console.

Review the provider's official pricing page, rate limits, and developer documentation regularly. As of September 2026, model availability, prices, and endpoint behavior can all change; official pages are the only reliable source. For HeFu, refer to the HeFu pricing page and the HeFu developer docs. The same principle applies to other open-source clients such as Open WebUI or Cline when configuring OpenAI-compatible providers.

FAQ

Should the base URL be the root address or the full endpoint address?

Use the root address, e.g., https://api.hefu.hk/v1. An OpenAI-compatible client normally appends /chat/completions automatically after the Base URL; if you paste the full endpoint address into the Base URL field, the client may construct a doubled path such as /v1/chat/completions/chat/completions. To verify, inspect the request log in Cherry Studio or on the provider side and confirm the actual request path.

After adding a custom provider, the model list is empty or reports "model not found". What should I do?

A custom OpenAI-compatible provider does not automatically sync the remote model directory. Copy the full model ID from the provider's official model catalog, add it to Cherry Studio's model list, and confirm that the current API key's account is authorized for that model. If the error persists, compare the ID character by character: any extra whitespace or case error will trigger "model not found." For HeFu, use the HeFu model catalog as the authoritative source.

Can I use an Anthropic key in an OpenAI-compatible provider?

No. Anthropic native API keys use the sk-ant- prefix, and an OpenAI-compatible endpoint will reject them with a 401 error (Anthropic Authentication). An aggregator gateway typically uses a unified key format to support multiple model families, so a single key can be used with Claude, GPT, DeepSeek, and others; however, this is a gateway behavior, not a guarantee of the OpenAI-compatible protocol itself.

Which endpoint should I use: /v1/chat/completions or /v1/responses?

For OpenAI-compatible services, use /v1/chat/completions. OpenAI officially maintains both the Chat Completions API and the newer Responses API (OpenAI API Reference), but most third-party aggregation services implement only Chat Completions. As of September 2026, do not assume an aggregator gateway supports /v1/responses; follow the endpoints declared in the provider's official documentation. Claims that /v1/responses is restricted to certain legacy model generations have no OpenAI official source support and should not be used as configuration guidance.

Is it safe to share my API key in team configuration files?

No. An API key is an access and billing credential; store it in environment variables, a key management service, or Cherry Studio's encrypted storage. When sharing within a team, use individually revocable sub-keys and audit call logs and usage regularly. As of September 2026, prices, rate limits, and billing policies are subject to the provider's official pages — for HeFu, see the HeFu pricing page — and should not be sourced from third-party blogs or historical snapshots.