WorkBuddy

WorkBuddy supports HaiToken through custom models. The two most common ways are:

Add a custom model directly in the WorkBuddy UI for quick verification
Maintain models in local models.json for longer-term use or project-based management

The core configuration is the same in both paths:

Use the full endpoint https://api.haitoken.ai/v1/chat/completions
Use a real HaiToken model ID as the model name
Use your HaiToken API key

Protocol Note

WorkBuddy’s custom model integration only supports the OpenAI Chat Completions protocol; it does not support the Anthropic Messages protocol. This guide therefore only covers the OpenAI mode, with the request URL fixed to the full endpoint https://api.haitoken.ai/v1/chat/completions.

The WorkBuddy UI flow is usually very similar on Windows, macOS, and Linux. The parts that are more likely to differ by system are models.json paths, environment-variable syntax, and how ~ maps to your user home directory.

What You Need

A HaiToken API key
At least one available model ID, such as gpt-5.4
Full chat completions endpoint: https://api.haitoken.ai/v1/chat/completions

Quick Mapping

Item	Meaning
Actual request endpoint	`https://api.haitoken.ai/v1/chat/completions`
Protocol	OpenAI Chat Completions
Auth header	`Authorization: Bearer YOUR_API_KEY`
Model source	A custom model added in the UI or registered in local `models.json`

In WorkBuddy, this is not a generic Base URL. You should enter the full endpoint https://api.haitoken.ai/v1/chat/completions.

In WorkBuddy, whether you use the quick UI flow or models.json, the model field should contain the model ID from the HaiToken homepage or model list, not the display name. The display name can be customized, but the request actually matches on the model ID.

Mode 1: Add It Quickly in the WorkBuddy UI

This is the best path for a first validation.

Step 1: Open the custom model entry

In the chat UI, click the current model and choose Configure Custom Model from the dropdown.

Step 2: Choose `Custom`

In the add-model dialog, choose Custom in the provider list.

Step 3: Fill the HaiToken values

Use the following values and then click Save:

Field	Recommended value
Provider	`Custom`
Endpoint	`https://api.haitoken.ai/v1/chat/completions`
API Key	Your HaiToken API key
Model name	A real HaiToken model ID such as `gpt-5.4`

Step 4: Adjust advanced options if needed

If the current UI exposes capability toggles, match them to the real model capability:

Enable Tool Call only if the model supports tools
Enable Reasoning only if the model supports reasoning mode
Do not enable image capability if the model does not support image input

Step 5: Return to chat and test it

Switch to the newly added model and send a simple message such as hi. If a normal response comes back, the integration is working.

Checklist

The model appears in the model dropdown.
A simple test request returns normally.
If this WorkBuddy entry supports streaming, the reply appears progressively instead of only at the end.

FAQ

Question	Fix
The model does not appear in the list	Check whether the model name is a real HaiToken model ID, whether the endpoint is the full URL `https://api.haitoken.ai/v1/chat/completions`, and whether you reopened the model list or reopened WorkBuddy after saving.
Authentication error	Make sure the API key you entered is valid and does not include extra spaces.
The request is sent but the model does not respond	Check whether the model ID exists, whether the endpoint is complete, and whether you enabled options that the current model does not support.

The UI flow is better for quick verification. If you want to manage multiple models or keep project-specific model lists, use the models.json flow below.

Mode 2: Configure Local `models.json`

This path is better for long-term model management. WorkBuddy / CodeBuddy commonly uses two config scopes:

User-level: ~/.codebuddy/models.json
Project-level: <project-root>/.codebuddy/models.json

You can read that differently by operating system:

Windows: ~ usually maps to %USERPROFILE%, so the user-level path is commonly understood as %USERPROFILE%\\.codebuddy\\models.json
macOS: ~ usually maps to /Users/<your-name>
Linux: ~ usually maps to /home/<your-name>

If you only want HaiToken in the current project, use the project-level config first. If you want it visible everywhere, use the user-level config.

Step 1: Choose the scope and create `models.json`

Decide where the config should live, then create or edit models.json there. Save the file as UTF-8 without BOM. Some desktop builds fail to read models.json when it includes BOM.

Step 2: Add the HaiToken models

Example:

{
  "models": [
    {
      "id": "gpt-5.4",
      "name": "HaiToken GPT-5.4",
      "vendor": "HaiToken",
      "url": "https://api.haitoken.ai/v1/chat/completions",
      "apiKey": "${HAITOKEN_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true,
      "supportsImages": false,
      "supportsReasoning": true
    },
    {
      "id": "gpt-5.4",
      "name": "HaiToken GPT-5.4",
      "vendor": "HaiToken",
      "url": "https://api.haitoken.ai/v1/chat/completions",
      "apiKey": "${HAITOKEN_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true,
      "supportsImages": false,
      "supportsReasoning": true,
      "relatedModels": {
        "lite": "gpt-5.4",
        "reasoning": "gpt-5.4"
      }
    }
  ],
  "availableModels": [
    "gpt-5.4",
    "gpt-5.4"
  ]
}

Step 3: Set the environment variable

If you use ${HAITOKEN_API_KEY}, set the variable before starting WorkBuddy. Windows PowerShell:

$env:HAITOKEN_API_KEY = "YOUR_API_KEY"

macOS / Linux:

export HAITOKEN_API_KEY="YOUR_API_KEY"

Step 4: Save and reload WorkBuddy

After saving the file, first check whether WorkBuddy refreshes the model list automatically. If the model still does not appear, fully close WorkBuddy and reopen it once.

Key Notes

`url` must be the full endpoint

Whether you add the model in the UI or register it in models.json, url must point to the full endpoint:

https://api.haitoken.ai/v1/chat/completions

Do not use:

https://api.haitoken.ai
https://api.haitoken.ai/v1

`apiKey` becomes a Bearer token

WorkBuddy expects the following auth pattern:

Authorization: Bearer YOUR_API_KEY

If apiKey is written as ${HAITOKEN_API_KEY}, WorkBuddy resolves it and sends it as Authorization: Bearer ..., not as X-Api-Key.

What `availableModels` does

When you use models.json, availableModels controls which models appear in the WorkBuddy dropdown. It does not decide whether HaiToken actually supports the model.

How `availableModels` relates to `/v1/models`

These are easy to confuse:

GET /v1/models is the set of models visible to your current HaiToken API key
models[].id is the local model ID you register in WorkBuddy and must match a real HaiToken model ID
availableModels is only the local display allowlist in WorkBuddy

You can think of it like this: local models.json controls what WorkBuddy shows and tries to call, while HaiToken GET /v1/models helps you confirm whether your API key actually has access to those models. Check visible models first if needed:

curl https://api.haitoken.ai/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Then copy the returned id values exactly into the UI or into models[].id, and decide whether to include them in availableModels.

When `relatedModels` is useful

If you want a main model to switch automatically to a faster or stronger model in different cases, configure relatedModels.

lite usually points to a faster and cheaper model
reasoning usually points to a stronger reasoning model

Checklist

WorkBuddy shows HaiToken GPT-5.4 or the name you configured in the model dropdown.
A simple conversation returns normally without auth failures or missing-model errors.
If the current entry supports streaming, the reply appears incrementally rather than only at the end.

FAQ

Question	Fix
The model does not appear in the list	If you used the UI flow, check whether the model ID matches the value returned by HaiToken `GET /v1/models`, whether `url` is the full endpoint, and whether you reopened WorkBuddy or the model list after saving. If you used `models.json`, also check whether the file path is correct, whether the JSON syntax is valid, and whether `availableModels` includes your model ID.
Authentication error	Make sure the API key is valid, or make sure `HAITOKEN_API_KEY` exists in the same environment where WorkBuddy starts.
`404` or connection error	This is usually a wrong `url`. WorkBuddy must use the full endpoint `https://api.haitoken.ai/v1/chat/completions`.
The response returns, but not as a stream	First confirm that the current WorkBuddy entry actually supports streaming. If it does but still behaves oddly, try another model first. HaiToken supports SSE streaming and already adapts some client-side streaming compatibility headers.

VPN or proxy connection issues

If a VPN, system proxy, or TUN mode causes a connection error or timeout, see VPN and proxy connectivity. It explains the difference between system proxies and TUN mode, including the corresponding WorkBuddy setting.

Quick start

API documentation

AI tool integration

Other

Protocol Note

What You Need

Quick Mapping

Mode 1: Add It Quickly in the WorkBuddy UI

Step 1: Open the custom model entry

Step 2: Choose `Custom`

Step 3: Fill the HaiToken values

Step 4: Adjust advanced options if needed

Step 5: Return to chat and test it

Checklist

FAQ

Mode 2: Configure Local `models.json`

Step 1: Choose the scope and create `models.json`

Step 2: Add the HaiToken models

Step 3: Set the environment variable

Step 4: Save and reload WorkBuddy

Key Notes

`url` must be the full endpoint

`apiKey` becomes a Bearer token

What `availableModels` does

How `availableModels` relates to `/v1/models`

When `relatedModels` is useful

Checklist

FAQ

VPN or proxy connection issues

Next

​Protocol Note

​What You Need

​Quick Mapping

​Mode 1: Add It Quickly in the WorkBuddy UI

​Step 1: Open the custom model entry

​Step 2: Choose Custom

​Step 3: Fill the HaiToken values

​Step 4: Adjust advanced options if needed

​Step 5: Return to chat and test it

​Checklist

​FAQ

​Mode 2: Configure Local models.json

​Step 1: Choose the scope and create models.json

​Step 2: Add the HaiToken models

​Step 3: Set the environment variable

​Step 4: Save and reload WorkBuddy

​Key Notes

​url must be the full endpoint

​apiKey becomes a Bearer token

​What availableModels does

​How availableModels relates to /v1/models

​When relatedModels is useful

​Checklist

​FAQ

​VPN or proxy connection issues

​Next

Protocol Note

What You Need

Quick Mapping

Mode 1: Add It Quickly in the WorkBuddy UI

Step 1: Open the custom model entry

Step 2: Choose `Custom`

Step 3: Fill the HaiToken values

Step 4: Adjust advanced options if needed

Step 5: Return to chat and test it

Checklist

FAQ

Mode 2: Configure Local `models.json`

Step 1: Choose the scope and create `models.json`

Step 2: Add the HaiToken models

Step 3: Set the environment variable

Step 4: Save and reload WorkBuddy

Key Notes

`url` must be the full endpoint

`apiKey` becomes a Bearer token

What `availableModels` does

How `availableModels` relates to `/v1/models`

When `relatedModels` is useful

Checklist

FAQ

VPN or proxy connection issues

Next