Connect Ollama with WorkBuddy: Local AI Setup Guide

Introduction

Tencent WorkBuddy released its on-premise deployment capability in 2026. This custom model feature enables developers to run open-source large language models locally via Ollama, then connect the models to WorkBuddy chat and agent workflows through OpenAI-compatible API protocol. All configuration parameters are saved locally within the models.json file, and the entire workflow consumes no WorkBuddy built-in credits. This article builds upon the official WorkBuddy model configuration documentation and Ollama Quickstart. It walks readers through the full pipeline, covering installation, model pulling, service connectivity, troubleshooting, model selection, capability toggles, and comparisons against cloud-based alternatives. The local deployment pattern delivers zero software cost, with only hardware power consumption as the ongoing expense, and supports complex multi-turn agent tasks offline.

Core Definition: What is WorkBuddy Local Deployment

WorkBuddy local deployment treats WorkBuddy as a communication relay layer. User prompts are forwarded directly to the local Ollama service instance. According to WorkBuddy official configuration documents, after Ollama starts, it listens on the local HTTP port, defaulting to port 11434, and exposes an OpenAI-compatible API endpoint for WorkBuddy integration. API keys and other configuration metadata persist locally inside the workbuddy/models.json file.

This architecture brings three critical characteristics. All conversation and code data never leave the local machine. Requests bypass WorkBuddy cloud servers, and no built-in platform credits are deducted. The whole system works offline. Agent invocation, skill assembly and multi-round dialogue retain full functionality, with the underlying model switched to a self-hosted local model.

Why Choose Ollama: Three Core Business Scenarios

Long-term usage of cloud-hosted models often creates cost pressure from token and credit consumption. Ollama fills this gap effectively.

1. Data Privacy and Compliance: Code and chat content stay within local devices. This fits financial, government and sensitive internal project scenarios where data leakage risks must be minimized.
2. Zero Trial Expense: There is no token billing or paid API charges. Users only leverage their existing hardware computing resources.
3. Offline Operation: WorkBuddy can run on planes, isolated intranet workstations, and environments without internet access.

The September 2026 note in WorkBuddy official documentation clarifies that fees generated by custom models are charged by third-party service providers, fully separated from WorkBuddy platform billing. For a local Ollama setup, there are no third-party billing items, and the only overhead comes from electricity consumption for hardware operation.

Pre-requisite Setup: Install Ollama and Launch the First Model

We use Qwen, widely adopted by Chinese-speaking developers, as the demonstration model. Three simple shell commands complete the basic environment setup.

ollama --version
ollama pull qwen3:4b
ollama run qwen3:4b "Introduce yourself."

Three key verification points extracted from the Ollama official Quickstart guide (September 2026):

• The default service port for Ollama is 11434. WorkBuddy connects to this OpenAI-compatible endpoint.
• Reference package specification: Gemma 4 E2B model installer package is about 7.2 GB. 8 GB available VRAM is recommended for running this model on Mac systems with unified memory. If VRAM is insufficient, the model falls back to system RAM with degraded inference speed.
• Model names must exactly match the output of ollama list. Names are case-sensitive in subsequent WorkBuddy configuration.

On Linux systems, the service will not start automatically, so users need to manually execute ollama serve. Windows and macOS launch the service automatically once the application is installed and the icon is active. Developers should verify the API connectivity in the browser before opening WorkBuddy to save debugging time.

Use this curl command to test the local endpoint:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3:4b",
    "messages": [{"role": "user", "content": "Say one sentence."}]
  }'

Proceed to WorkBuddy configuration only after this curl test returns valid responses.

Three-step Integration via Graphical UI

Custom model support in WorkBuddy allows visual modification without manually editing configuration files.
Step 1: Open the model selector. Navigate to the bottom model picker on WorkBuddy’s main interface. Scroll down and select custom model to enter the configuration page.
Step 2: Add Ollama provider. Click add model on the top-right corner, then select Ollama local from the provider dropdown. The API address will populate automatically without manual path entry.
Step3: Fill parameters and save the configuration:

• API endpoint: http://localhost:11434/v1/chat/completions
• API Key: ollama
• Model name: qwen3:4b

Click save. The new model group will appear inside the conversation model selector, ready for direct chat. To switch models, pull another model with ollama pull, then modify the model name inside this configuration entry.

Batch Configuration: Edit models.json to Register Multiple Local Models

The models.json file supports bulk import of multiple local models. Direct file editing is faster for team environments with multiple model variants. The official WorkBuddy document confirms the file path as local workbuddy/models.json. The configuration example below demonstrates the format.

{
  "models": [
    {
      "id": "qwen3:4b",
      "name": "Qwen 3 4B (Local)",
      "vendor": "ollama",
      "apiKey": "ollama",
      "url": "http://localhost:11434/v1/chat/completions",
      "supportsToolCall": false
    }
  ]
}

Field explanation:

• id: This value is passed as the API model parameter and must match the name listed by ollama list.
• name: Display name shown on the dropdown menu; users can customize it freely.
• url: Fixed endpoint format for local Ollama service.

For small parameter models, disable tool calling and image input to improve stability. Older models configured in ~/.codebuddy/models.json remain functional after WorkBuddy upgrades.

Model Selection and Feature Toggle: Reviving Agent Workloads with 4B Models

WorkBuddy provides three runtime modes: fast mode for quick customer replies, balanced mode for document modification tasks, and extreme mode for cross-file refactoring. Default settings are acceptable for most scenarios. According to WorkBuddy official documents, the context window limit is 200k characters for each round of message transmission. When memory is constrained, users can enable the sliding window strategy.

Local models carry inherent limitations. When asking a lightweight local model to handle hundreds of code changes and cross-file reconstruction in a single request, repeated errors are common. In such heavy workloads, developers can route complex requests to cloud models via OpenAI compatible endpoints. Treerouter, an API gateway, can manage unified routing for hybrid local and cloud model workloads.

Troubleshooting Framework: Debug Ollama First, Then WorkBuddy

When integration fails, always validate the Ollama service before checking WorkBuddy configuration.

1. Connection failure: Run curl test for port 11434. Common causes include inactive Ollama service, port occupation, or firewall interception.
2. Truncated or garbled output: Insufficient RAM or VRAM. Switch to smaller models, or adjust custom protocol headers if non-standard gateways are used.
3. Tool call malfunction: Small local models often lack reliable tool invocation capability. Users need to set supportsToolCall correctly inside models.json.
4. API key warning: Local Ollama deployment does not validate API keys. Ignore key mismatch alerts once the endpoint test succeeds.

Frequently Asked Questions

Q: Why does WorkBuddy report connection timeout or 400 error?

Common triggers include incorrect address formatting, model name inconsistent with ollama list, gateway encapsulation issues or custom protocol mismatches. Run curl validation for port 11434 first, then recheck WorkBuddy model configuration.

Q: Can WorkBuddy connect remote Ollama deployment?

Yes. WorkBuddy custom model API supports remote Ollama instances. Modify the endpoint address to the remote machine address with port 11434. Remote Ollama deployment counts as one of three integration modes, together with cloud third-party API and local deployment.

Conclusion

WorkBuddy’s Ollama integration essentially shifts computing workloads from cloud servers to local hardware. Ollama manages model runtime, and WorkBuddy handles conversation and agent orchestration. This solution combines WorkBuddy agent capabilities with self-hosted open-source models. Based on WorkBuddy official documents and Ollama Quickstart, all configuration is saved locally, and the pipeline eliminates platform credit consumption. This article is compiled from materials available as of September 17, 2026. Readers should cross-check the latest parameters from official documentation for production deployment.

Learn more：https://treerouter.com