Introduction

WorkBuddy’s custom model connector enables users to integrate any third-party OpenAI-compatible API endpoints into WorkBuddy conversations and Agent workflows. This feature bypasses built-in platform credit billing, allowing you to directly consume your own model quotas. All custom model configurations are saved locally within ~/.workbuddy/models.json and are never uploaded to remote servers. Supported services include official DeepSeek APIs, Kimi, GLM, local Ollama deployments, and any compatible endpoints exposed via middleware such as Treerouter.

You may find custom model integration suitable if you match any of the following scenarios:

  • You already own API quota from DeepSeek, Kimi or other platforms and wish to avoid duplicate subscription costs within WorkBuddy.
  • You need access to model variants that are not listed inside WorkBuddy’s native model menu.
  • You run open-source models locally through Ollama and want fully offline workflows without outbound internet calls.
  • You plan to connect a unified API routing layer to manage multiple LLMs, switching models with a single API key.

When you connect external custom models, all usage charges are billed directly by your chosen API provider, completely separate from WorkBuddy’s native credit system. This tutorial covers two primary configuration workflows: graphical UI setup for beginners, and manual models.json file editing for bulk or automated deployments.

Method 1: Graphical User Interface Configuration (Recommended for New Users)

This workflow requires no direct file editing and can be completed in three clear steps.

Step 1: Open the Model Configuration Entry

On WorkBuddy’s main interface, click the model selector at the bottom bar, which displays your currently active model. Scroll to the bottom of the popped model list and select Configure Custom Model.

Step 2: Add Model Entry and Select Provider

Navigate to the Model settings page and click Add Model in the top-right corner. A modal window will appear, marked to accept only OpenAI-compatible API endpoints. The provider dropdown menu contains preset options:

Category Available Providers
Coding Plan Kimi Coding Plan
Custom API Zhipu Open Platform / GLM API, Kimi China, MiniMax China, DeepSeek, Local Ollama
Others Custom / Custom (for any generic compatible endpoints)

If you select a preset provider, the standard API endpoint will populate automatically; you only need to input your API Key and save the configuration. If you select Custom / Custom, all connection parameters must be filled manually, as covered in Step 3.

Step 3: Fill in API Connection Information and Save

Four core fields are required for custom provider connections:

  1. API Endpoint: The full chat/completions URL of your service. Example format: https://api.example.com/v1/chat/completions
  2. API Key: Your private authentication key issued by the service provider.
  3. Model Name: The exact model identifier passed to the API within the model request field.
    • DeepSeek official: deepseek-chat, deepseek-reasoner
    • Kimi: moonshot-v1-8k, kimi-k2
    • Local Ollama: llama3.2, qwen2.5:7b (match the output from the ollama list command) After filling all parameters, click Save. The new model will appear immediately in WorkBuddy’s global model selector for direct use.
Advanced Configuration Options

The modal also exposes optional tuning parameters that control runtime behavior inside WorkBuddy:

  • Tool Calling: Enable this if your target model supports function calling. When activated, WorkBuddy Agents and embedded Skills can invoke external tools including web search and code execution. This option will have no effect if the underlying model lacks native function call support.
  • Image Input: Toggle this to allow image uploads for multimodal vision models. Leave this unchecked for pure text LLMs, otherwise request failures will occur.
  • Reasoner Mode: Designed for reasoning-focused models such as DeepSeek-R1. It enables native `` block parsing, and only works for models that support this output format.
  • Custom Protocol: Check this box for non-standard endpoints or gateways with modified URL structures. If your endpoint does not end with /chat/completions, this option prevents automatic path correction.
  • Context Window: Manually define the token limit for input and output. Leave blank to inherit the provider’s default value if you are unsure of the exact maximum context length.

Method 2: Direct models.json File Editing (For Bulk Configuration)

If you need to add multiple models in batches or automate deployments via scripts, you can modify the configuration file directly. File paths by operating system:

  • macOS / Linux: ~/.workbuddy/models.json
  • Windows: C:\Users\[Your Username]\.workbuddy\models.json

Sample JSON Structure

{
  "models": [
    {
      "id": "deepseek-chat",
      "name": "DeepSeek Chat",
      "vendor": "DeepSeek Official",
      "apikey": "sk-XXXXXXXXXXXXXXXX",
      "url": "https://api.deepseek.com/v1/chat/completions",
      "supportsToolCall": false,
      "supportsImages": false
    }
  ]
}

Full Field Reference Table

Field Mandatory Description
id Yes The official model identifier sent to the API in each request
name Yes Display name visible inside WorkBuddy’s UI; can be customized freely
vendor Yes Label for the service provider, used for organization within the interface
apikey Yes Authentication key; use ollama as the key value for local Ollama instances
url Yes Complete chat/completions API endpoint URL
supportsToolCall No Boolean flag to enable function calling, default value false
supportsImages No Boolean flag to enable multimodal image input, default value false

After saving changes to the file, WorkBuddy will reload the configuration automatically within approximately one second; no application restart is required.

Standard API Endpoint Quick Reference Table

This table lists commonly used endpoints for mainstream LLM providers and corresponding example model IDs.

Provider API Endpoint URL Example Model Name
DeepSeek Official https://api.deepseek.com/v1/chat/completions deepseek-chat
Zhipu GLM https://open.bigmodel.cn/api/paas/v4/chat/completions glm-5-plus
Kimi China https://api.moonshot.cn/v1/chat/completions moonshot-v1-8k
MiniMax https://api.minimax.chat/v1/text/chatcompletion_v2 MiniMax-Text-01
Local Ollama http://localhost:11434/v1/chat/completions llama3.2
Treerouter https://treerouter.com/v1/chat/completions Refer to your gateway model list

Using a unified routing layer like Treerouter streamlines management significantly: you only configure one endpoint and one key inside WorkBuddy, and you can switch between dozens of distinct models without repeatedly adding separate model entries.

Frequently Asked Troubleshooting

Q: Connection failure appears after adding a custom model

Check these items sequentially:

  1. Verify endpoint URL accuracy; watch for trailing whitespace and confirm the path ends with chat/completions. Enable the Custom Protocol checkbox if your gateway uses a non-standard route.
  2. Confirm your API Key has been copied completely, with no hidden extra characters.
  3. Double-check the model name matches the exact identifier recognized by your provider; model IDs are case-sensitive.

Q: How to set up local Ollama models

Confirm Ollama service is running locally on http://localhost:11434. Enter the local endpoint in WorkBuddy, set the API Key to ollama, and use the exact model tag shown by the ollama list command as your model name.

Q: Does custom model usage consume native WorkBuddy credits?

No. All traffic is forwarded directly to your specified external API. Billing is handled entirely by your provider, independent of WorkBuddy’s internal credit balance.

Q: Is the API Key stored securely inside models.json?

All configuration data remains local on your device and will never be synced to WorkBuddy cloud servers. Note that models.json is plain-text JSON. Do not upload this file to public Git repositories or share it with third parties to prevent credential leaks.

Best Practices and Summary

WorkBuddy’s custom model module acts as a lightweight OpenAI-compatible API forwarder. Any service exposing a standard chat/completions endpoint can be integrated, provided you supply a valid API key and matching model identifier. The graphical configuration workflow is recommended for most users, while direct models.json editing is suited for bulk deployment and DevOps automation. When configuring multimodal models or agent workflows with tool calling, remember to toggle the corresponding advanced options to unlock full functionality. Incorrect parameter settings are the most common source of timeouts and malformed requests.

As you scale your stack of self-managed LLM endpoints, a centralized API gateway such as Treerouter reduces configuration overhead and simplifies traffic governance across all your AI client applications.

For the latest platform updates, refer to official documentation at codebuddy.cn/docs/workbuddy.