Fix WorkBuddy Custom Models: API, Auth and Protocols

Introduction

Failed custom model connection within WorkBuddy rarely stems from fundamental model malfunctions. In most cases, requests cannot reach the target API endpoint successfully, or the returned payload format cannot be parsed correctly by WorkBuddy. A structured troubleshooting workflow starts with curl validation of network connectivity and API key validity, followed by verification of endpoint addresses and model identifiers, and final checks for tool calling, image input, reasoning mode and context window parameter compatibility. This article maps common error phenomena to executable inspection commands, helping engineers distinguish between configuration mistakes, provider-side restrictions and WorkBuddy client-side parsing defects.

The request delivery chain for custom model integration can be split into five layers: WorkBuddy configuration, network connectivity, authentication, model routing and response protocol. Each layer requires distinct remediation methods. Repeatedly switching model names will not resolve network or protocol incompatibility issues.

Symptom	Primary Suspected Root Cause	First Inspection Action
Invalid address prompt on saving	URL format or auto-completion error	Verify full /chat/completions path entry
401/403 status code	Invalid key, permission or incorrect request header	Isolate endpoint testing via independent curl request
404 / Model not found	Wrong model ID or regional endpoint mismatch	Cross-check provider model list and official documentation
Connection timeout	Network, DNS or TLS handshake failure	Inspect handshake and raw response with curl -v
Response parsing failure	Non-standard OpenAI Chat Completions payload	Validate JSON schema and streaming format
Standard chat works, Agent workflow fails	Tool Calling protocol incompatibility	Disable tool invocation for A/B testing
Text input works, image upload fails	Model or endpoint lacks multimodal vision support	Run minimal validation with image_url payload

Step 1: Verify Correct Configuration Saved in WorkBuddy

The custom model form in WorkBuddy requires at minimum three core parameters: endpoint address, API Key and model identifier. Endpoint URLs must strictly follow the provider’s official specification. If the interface requires a complete endpoint entry, the value should resemble https://api.example.com/v1/chat/completions.

Avoid redundant filling of base URL and full endpoint path in the same field. For instance, do not input https://api.example.com/v1 together with the appended /chat/completions path, which will create duplicated routing strings. If the interface provides an option for custom protocol or raw payload forwarding, this feature is only necessary when the upstream provider does not comply with the standard OpenAI Chat Completions schema.

The model name field must exactly match the model identifier accepted by the provider API, rather than the display name on web dashboards. Uppercase and lowercase characters, hyphens and version suffixes directly affect routing logic. As an example, deepseek-chat and DeepSeek Chat will be recognized as separate identifiers by most service backends.

Local Configuration File Inspection

If the newly added model disappears after saving on the graphical interface, close WorkBuddy and check whether the local configuration file has been written successfully. The storage path varies across releases, and the snippets below serve as common references, subject to official version specifications.

# Example for macOS / Linux
ls -l ~/.workbuddy/models.json
python3 -m json.tool ~/.workbuddy/models.json

If the json.tool parsing returns errors, the file contains redundant commas, mismatched quotation marks or truncated content. API keys should never be committed to Git repositories, and complete configuration files should not be shared on public forums.

Step 2: Isolate WorkBuddy with Independent Curl Testing

This is the most critical diagnostic step: send requests directly to the upstream provider endpoint without involving WorkBuddy. Replace YOUR_API_KEY, MODEL_ID and URL with real values for validation:

curl -sS -i https://api.example.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MODEL_ID",
"messages": [{"role": "user", "content": "ping"}],
"max_tokens": 16,
"stream": false
}'

Interpret HTTP status codes and response bodies as follows:

• 200: Network, key and model routing function normally. Proceed to inspect field mapping within WorkBuddy.
• 401: Invalid, expired or whitespace-contaminated API key, or non-standard authentication headers required by the provider.
• 403: The account lacks access permissions for the target model, restricted by region or IP whitelisting policies.
• 404: Incorrect endpoint path or invalid model ID.
• 429: Quota exhaustion, concurrency or rate limiting. This is not a WorkBuddy configuration error.
• 5xx: Server-side fault from the upstream provider or upstream gateway anomaly.

If the basic command times out, execute the extended test below to diagnose network layer issues:

curl -v --connect-timeout 10 --max-time 30 https://api.example.com/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"

Focus on DNS resolution, TLS handshake, proxy and certificate exceptions. If the endpoint is reachable via terminals but inaccessible inside WorkBuddy, verify whether WorkBuddy uses an isolated network stack, system proxy or sandbox permission controls.

Teams managing multiple model vendors can unify heterogeneous endpoints via 4sapi as an OpenAI-compatible gateway for centralized validation. Engineers can complete the above curl single-point verification against the unified entry before importing valid parameters to WorkBuddy.

Step 3: Distinguish Protocol Incompatibility and Native Model Limitations

"OpenAI-compatible" only describes similar request formatting. It does not guarantee full compliance across all JSON fields and streaming behaviors. Core requests in WorkBuddy depend on standard keys including model, messages, max_tokens and stream. Endpoints built on Responses API, Anthropic Messages API or fully custom JSON schemas often trigger 404 errors, empty payloads or streaming parsing failures when directly imported.

Run the following Python script to print raw responses and validate whether the result includes the required choices[0].message.content structure:

import json
import os
import requests

url = "https://api.example.com/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {os.environ['MODEL_API_KEY']}",
    "Content-Type": "application/json",
}
payload = {
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens":16,
    "stream":False
}
resp = requests.post(url, headers=headers, json=payload)
print(json.dumps(resp.json(), indent=2, ensure_ascii=False))

If non-stream requests succeed while streaming calls fail, the root cause usually lies in SSE event formatting, proxy buffer interference or WorkBuddy’s streaming parser. Disable streaming output temporarily (if supported by the WorkBuddy release) for verification before implementing a compatibility gateway.

Troubleshooting Tool Calling Failures

If regular conversations run normally but WorkBuddy Agent workflows report errors, the top cause is lack of native Function Calling support on the model side, or non-standard tool_call fields returned by the provider that deviate from OpenAI specifications. The recommended workflow is to toggle off tool invocation in the configuration, confirm stable plain-text task execution, and then re-enable tool calling incrementally. At minimum, three validation criteria must be satisfied:

1. Official model documentation explicitly confirms native function/tool calling capability
2. The endpoint correctly accepts tools and tool_choice parameters
3. Return payload contains properly formatted tool_calls and supports subsequent messages with role=tool

Sample minimal test payload for tool invocation verification:

curl -sS https://api.example.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MODEL_ID",
"messages": [{"role": "user", "content": "Query the weather in Beijing"}],
"tools": [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
    }
}]
}'

If the provider only supports rigid predefined tool templates, do not activate tool calling directly within WorkBuddy. Switch to a model that fully complies with the protocol, or deploy a transformation gateway to standardize payloads. Do not confuse raw JSON output from models with native tool calling capability.

Troubleshooting Image Input Failures

Image multimodal requests require three preconditions simultaneously: the model supports vision capabilities, the endpoint accepts multimodal content arrays, and the image_url resource is publicly accessible from the server side. A minimal valid JSON example is shown below:

{
    "model": "VISION_MODEL_ID",
    "messages": [{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe the content of this picture"},
            {"type": "image_url", "image_url": {"url": "https://example.com/a.png"}}
        ]
    }]
}

If text requests pass but image submissions return 400 errors, first confirm that WorkBuddy’s image upload toggle matches the model’s vision capability. Image URLs requiring login or internal network access cannot be downloaded by remote servers. In such cases, use temporary public URLs or convert files to Base64 encoding per provider requirements. Excessive file size or unsupported formats also lead to silent failures.

Anomalies Triggered by Reasoning Modes and Context Window Settings

Many models include dedicated reasoning parameters. WorkBuddy’s additional settings such as thinking budget, output temperature and context limits may trigger unexpected truncation or failures if misaligned with model specifications. If the model has a hard maximum context limit, exceeding this threshold will result in failures, rather than automatic compression. It is advised to test with conservative parameters such as max_tokens=4k and context_length=16k. Record first-byte latency, full response duration and cutoff behavior, to confirm whether failures are related to context overflow. When providers return context_length_exceeded, prioritize reducing historical message volume instead of adjusting client-side configuration blindly.

Rapid Localization by Error Messages

• Model not found: Confirm the model ID matches the real identifier used by the provider API, and verify region and plan permissions for the account. Do not directly copy dashboard display names.
• Invalid URL or repeated path: Check duplicated /v1 or /chat/completions strings, and invisible whitespace characters in URLs. Validate raw strings via python3 -c or text editors.
• Unauthorized: Regenerate API keys and remove extra whitespace. Confirm WorkBuddy does not stack duplicate Bearer prefixes or authentication logic. Avoid embedding keys in URL query strings.
• Empty response: Disable streaming, tool calls and reasoning modes, retaining only plain-text requests. If curl returns valid data but WorkBuddy shows empty output, capture raw response payloads to assess client parsing compatibility.
• Too many requests: Inspect provider RPM/RPM limits and WorkBuddy concurrent task configuration. Rate limit mitigation only relieves 429 errors and cannot resolve invalid keys or permission defects.

Reusable Standard Troubleshooting Sequence

1. Copy and verify endpoint URL, model ID and advanced toggles inside WorkBuddy
2. Send plain-text, low max_tokens requests via curl
3. Print JSON response with Python to confirm valid choices[0].message.content
4. Enable streaming, tool invocation, image input and reasoning modes one by one, modifying only one variable per test
5. Finally raise context window, concurrency and output length limits, logging latency and failure rates

The core logic of this workflow: first confirm raw requests can succeed, then verify WorkBuddy parsing compatibility, and lastly validate whether model capabilities satisfy Agent business requirements.

Frequently Asked Questions

Q1: Configuration passes validation, yet the model does not appear in the selection list

This is typically caused by failed configuration writing, malformed JSON, empty model ID or client cache refresh issues. Run python3 -m json.tool to validate the file, correct syntax errors and restart WorkBuddy.

Q2: The API works on other clients but consistently fails in WorkBuddy

Compare complete request and response payloads, especially endpoint routing, streaming flags and tool calling fields. Many compatible endpoints only support basic chat and lack full Agent protocol compliance.

Q3: What is the first check point for local Ollama integration failure

Verify the Ollama service listening address, model name, and confirm WorkBuddy and Ollama reside within the same network environment.

Q4: Should I directly switch to a new API platform immediately

Only consider vendor migration after confirming the endpoint, key and model ID function normally via curl, and the incompatibility is confirmed between the response protocol and WorkBuddy. Blindly switching platforms often masks native configuration defects.

Conclusion

Custom model integration failures in WorkBuddy are most frequently caused by URL formatting errors, incorrect API keys, invalid model identifiers, incomplete OpenAI compatibility, and misconfigured reasoning/context parameters. Following this layered inspection sequence can pinpoint root causes rapidly, usually within minutes. Note that field names and available parameters may evolve alongside WorkBuddy releases; always cross-reference the official documentation for your installed version. For teams managing multi-model traffic routing and unified access governance, Treerouter can simplify heterogeneous model endpoint orchestration.

Learn more：https://treerouter.com