WorkBuddy custom model setup
Enter the URL, API key, and model name in the order shown, then verify the complete connection.
This guide uses WorkBuddy's current custom model interface. Prepare an OmniaKey API key and one exact model ID before opening WorkBuddy.
The finished form: choose Custom, enter https://api.omniakey.com/v1, paste your OmniaKey API key, and use an exact model ID such as deepseek-v4-flash.
The form, saved model details, and model picker were checked in the macOS app running WorkBuddy v5.3.14. Tencent Cloud's official instructions require at least v4.22.15 for this feature.
| WorkBuddy field | Value |
|---|---|
| Provider | Custom under the Other group |
| Interface address | https://api.omniakey.com/v1 |
| API Key | A key created in OmniaKey |
| Model name | For example, deepseek-v4-flash |
Before you start, prepare two items
An OmniaKey API key
Sign in to OmniaKey and open the API Keys page:
- Select Create key.
- Name it
WorkBuddy, then set a suitable limit and expiry. - Create it and immediately copy the new key.
Keep the key dialog open until you have pasted the credential into WorkBuddy. Do not put the key in screenshots, chat messages, or public files.
The account also needs available balance or trial credit. Creating a key only creates a credential; it does not guarantee that the account can fund a request.
An exact model ID
Open the OmniaKey model catalog, choose a currently available model, and copy the model ID shown on the page. For a first test, use:
deepseek-v4-flash
The ID must match exactly. Do not enter the display name DeepSeek V4 Flash, remove hyphens, or invent a shorter alias.
Step 1: Open Add model
Start WorkBuddy and open:
System Settings → Models → + Add model
On the Models page, select + Add model in the upper-right corner.
You can also enter from the bottom of a new task:
Model picker → + Configure custom model
If neither entry is available, update WorkBuddy to version v4.22.15 or later. Tencent Cloud's current instructions require at least this version for the interface.
Step 2: Choose Custom and complete four fields
Fill the form from top to bottom.
1. Choose the Custom provider
Open the Provider menu and select:
Custom
In v5.3.14, it appears under the Other group. Do not choose the built-in OpenAI, Tencent Cloud Token Plan, or another provider because those profiles do not use the OmniaKey interface address.
2. Enter the address through /v1
In Interface address or Base URL, enter exactly:
https://api.omniakey.com/v1
Do not copy the gray placeholder. It shows an example ending in /v1/chat/completions, but OmniaKey uses the Base URL https://api.omniakey.com/v1 in this field.
3. Paste the API key
Paste the key you copied from OmniaKey into API Key. Do not add quotation marks, whitespace, or the word Bearer; enter only the key value.
4. Enter the model name
Under Model name or Model ID, enter the exact catalog ID:
deepseek-v4-flash
The core form should now read:
Provider: Custom
Interface address: https://api.omniakey.com/v1
API Key: [your OmniaKey API key]
Model name: deepseek-v4-flash
For the first connection test, leave the remaining fields at their defaults and make sure Custom protocol is off. In v5.3.14, a new form starts with Tool calling on, Image input off, Reasoning mode off, Custom protocol off, and provider-default input and output limits. A verified deepseek-v4-flash preset appears below.
Step 3: Save, select the model, and test it
Select Save and return to a new task. Open the model picker at the bottom, find the custom model section, and choose deepseek-v4-flash.
Send one short test message:
Reply with exactly: Connection successful
A normal response confirms four parts of the setup at once:
- WorkBuddy saved the custom provider.
- The Base URL is correct.
- The API key is accepted and has usable credit.
- The key can access the selected model ID.
Finally, open OmniaKey Usage and confirm that the call appears with the expected model. This closes the verification loop from WorkBuddy to OmniaKey.
If the saved model does not appear immediately, close and reopen the picker. Fully quit and restart WorkBuddy if it still does not appear.
Recommended advanced settings for the first test
Do not change several capability controls before basic chat works. A new custom model in WorkBuddy v5.3.14 starts with:
| Option | New-form default |
|---|---|
| Tool calling | On |
| Image input | Off |
| Reasoning mode | Off |
| Custom protocol | Off |
| Input and output limits | Provider defaults |
Use these defaults to verify the URL, key, and model name first. Then adjust capabilities for the model.
Verified deepseek-v4-flash preset
The saved model and successful local replies used this configuration:
| Option | deepseek-v4-flash setting |
|---|---|
| Tool calling | Off |
| Image input | Off |
| Reasoning mode | On |
| Reasoning only | Off |
| Allow disabling reasoning | On |
| Custom protocol | Off |
| Default reasoning effort | Auto (use request-layer default) |
| Supported reasoning efforts | Leave Low, Medium, High, Extra High, and Maximum unchecked |
| Input and output limits | Provider defaults |
WorkBuddy reveals Reasoning only, Allow disabling reasoning, and effort controls after Reasoning mode is enabled. Leave effort on Auto for the first test.
When to enable tool calling
Enable Tool calling when WorkBuddy needs to read files, use connectors, or perform agent tasks. The model must also support structured tool calls. deepseek-v4-flash currently has tool support in the OmniaKey catalog, so enable it after basic chat works and begin with a read-only task. It can remain off for a connection-only chat test.
When to enable image input
Enable it only for a model explicitly marked as accepting images. A client switch cannot add vision capability to a text-only model.
When to enable reasoning mode
Enable it when the catalog or model documentation explicitly lists reasoning, thinking, or a similar mode. Keep automatic effort and Allow disabling reasoning. Do not add unsupported effort values, and do not make reasoning-only mode the default for ordinary tasks.
Adding another model
Do not overwrite a working model entry. Open Add model again, keep the same OmniaKey URL and API key, replace only the exact model ID, and save it as another custom model.
Verify one model before adding the next. When a problem appears, this makes it clear which saved entry introduced it.
Troubleshooting by symptom
Configure custom model is missing
Check the WorkBuddy version first. Update to v4.22.15 or later, then look in the new-task model picker or under System Settings → Models.
HTTP 401, Unauthorized, or invalid API key
Copy the OmniaKey key again. Check for whitespace and make sure you did not paste Bearer with it. Confirm that the key is enabled and unexpired, and that both the account balance and key limit are usable.
Changing the model ID does not fix a 401; authentication failed before model selection mattered.
HTTP 404 or endpoint not found
The address must be exactly:
https://api.omniakey.com/v1
Do not use the bare domain, duplicate /v1, or append /chat/completions. Also make sure Custom protocol is off.
Model not found or UNKNOWN_MODEL
Copy the ID again from the live model catalog. A display name, guessed alias, or retired ID is not a valid current model ID.
Chat works but tools fail
The basic model connection is already working. Check WorkBuddy's Tool calling switch and the model's tool capability. Re-entering the API key or URL will not add tool support.
Image input fails
Both conditions must be true: the model supports images and WorkBuddy's Image input control is enabled.
The model is missing after Save
Confirm that you selected Save, then reopen the model picker. Restart WorkBuddy if necessary. If the configuration entry itself is unavailable, check the client version again.
Frequently asked questions
What OmniaKey URL should WorkBuddy use?
Use only https://api.omniakey.com/v1. It is a Base URL; WorkBuddy appends the operation path.
Do I need a models.json file?
No. This guide follows the current Configure custom model interface. Older local configuration file instructions describe a different setup path.
Can I configure GPT, Claude, Gemini, or another model?
Yes, when the model is currently listed in OmniaKey and supports the OpenAI-compatible route. Keep the same URL and use the exact catalog model ID.
Is MCP configured on this form?
No. This form configures the model API. MCP and connectors are separate WorkBuddy settings. Establish a basic model response before adding those tools.