Introduction

Custom model integration failure in WorkBuddy describes a set of common issues after developers connect third-party OpenAI-compatible services through the models.json configuration file or visual UI. Typical symptoms include missing model entries in selector lists, HTTP return codes such as 401, 403 and 404, request timeouts, and runtime Agent execution errors. In most cases, these problems stem from incomplete endpoint assembly, incorrect authentication settings or protocol mismatches rather than defects inside the large model itself.

This diagnostic framework covers two configuration pipelines supported by WorkBuddy and CodeBuddy: manual models.json file editing and graphical user interface setup. It applies to self-hosted services including vLLM, Ollama and LM Studio, as well as remote API providers wrapped by gateway services. The article adopts a layered troubleshooting workflow validated by developer community records from SegmentFault and developer forums, separating configuration, network, authentication, routing and protocol checks. It provides reproducible test steps and sample commands to accelerate root cause identification.

Core Facts and Configuration Rules

The key specifications below are extracted from WorkBuddy official documentation released in 2026:

  1. Two configuration tiers: User-level ~/.codebuddy/models.json and project-level <workspace>/.codebuddy/models.json. Project-level configuration overrides user-level settings.
  2. API endpoint constraint: WorkBuddy only accepts OpenAI-compatible interfaces. The URL must be a complete path ending with /chat/completions. Partial base URLs will trigger validation failures.
  3. Hot-reload mechanism: Configuration files trigger automatic reload within 1 second after edits. SmartMerge is applied for incremental merging. Custom models carry dedicated custom tags in the UI.
  4. Community verified troubleshooting sequence: First test network connectivity and API keys with curl commands. Validate model identifiers afterwards. Finally test tool calling, image rendering and reasoning capabilities incrementally.
  5. Five-layer fault chain: Failures can be traced across configuration, network, authentication, routing and response protocol layers. Simply changing model names rarely resolves underlying network and protocol defects.

This guide is not suitable for services that only implement Responses API or native Anthropic Messages format, without conversion gateways to translate requests into standard OpenAI chat completion payloads.

Layered Fault Diagnosis Matrix

Different visible symptoms point to distinct root causes. The table below maps phenomena, high-probability root causes and the first recommended diagnostic action.

Observed SymptomSuspected Root CausePriority Action
Prompt address invalid upon savingIncomplete URL pathVerify the full path ends with /chat/completions
HTTP 401 / 403 responseAPI key error or permission restrictionRun independent curl test of the API endpoint
HTTP 404 / model not foundIncorrect model IDCheck the provider’s available model list
Connection timeoutNetwork, DNS or TLS handshake failureExecute curl -v to inspect handshake logs
Parsing failure / empty responseNon-standard chat payload formatInspect the choices array and streaming format
Basic chat works, Agent functions failUnsupported tool calling schemaDisable tool calls and run A/B comparison
Text chat works, image generation failsMissing multimodal vision capabilityValidate with minimal image_url payload

Troubles should follow the five-layer sequence: configuration, network, authentication, routing and protocol. Iteratively modifying the model name without layered checks wastes debugging time.

Endpoint Assembly: Mandatory Full /chat/completions Path

A frequent root cause is incomplete endpoint construction. WorkBuddy strictly relies on the complete chat completion path. Base URLs alone cannot pass validation.

  • Valid examples:

https://api.openai.com/v1/chat/completions
http://localhost:11434/v1/chat/completions

  • Invalid examples:

https://api.openai.com/v1
http://localhost:11434

Developers should avoid mixing base URL segments and /chat/completions paths. Non-standard gateway paths require custom protocol switching inside WorkBuddy configuration, which skips built-in payload validation for direct forwarding.

When running multi-model parallel validation, developers can test connectivity for a single OpenAI-compatible endpoint first before importing the configuration to WorkBuddy. Copy-pasted content often contains invisible whitespace characters. Rewriting URLs manually after showing raw text in editors can eliminate hidden formatting errors.

Authentication and Model ID: Decoding 401, 403 and 404 Errors

HTTP status codes provide direct clues for authentication and identifier issues.

  • 200: Network, key and routing pass. Next inspect WorkBuddy field mapping rules.
  • 401: Wrong API key, expired credential, leading or trailing whitespace, or duplicated Bearer prefix headers.
  • 403: Missing model permissions, regional access limits or IP whitelist restrictions.
  • 404: Wrong path or incorrect model identifier. The id value must match the exact model parameter accepted by the API, not just the display name shown on web pages.
  • 429: Rate limit and concurrency throttling.
  • 5xx: Server-side failures originating from upstream providers or gateway services.
curl 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": "hi"}],
    "max_tokens":16
  }'

If the endpoint passes curl testing but fails inside WorkBuddy, check proxy rules and sandbox permission constraints for the local runtime environment.

Protocol Compatibility: Streaming and Responses Format Mismatch

OpenAI compatibility guarantees structural similarity of request and response schemas, not full consistency across all extended fields. This is the main source of empty outputs and parsing errors.

WorkBuddy core required fields include model, messages, max_tokens and stream. Services that only implement Responses API or native Anthropic format will directly return 400 errors or blank responses without format translation.

When non-stream and streaming modes are mixed, developers should isolate SSE event parsing issues. Proxy cache layers often corrupt streaming chunks. If curl returns valid content while WorkBuddy renders empty output, inspect the structure of choices[0].message.content. If this node is missing, the response payload violates expected schema requirements.

Agent Exclusive Troubleshooting: Tool Calling, Image Input and Long Context

Successful plain-text conversation does not guarantee Agent workflow availability. Advanced capabilities must be validated separately.

  1. Tool calling prerequisites: The provider must formally declare tool support, accept tools and tool_choice parameters, return standard tool_calls blocks and recognize the tool message role. Raw JSON output alone does not prove complete tool invocation compliance.
  2. Image input prerequisites: The model must support vision capabilities. Requests use multimodal content arrays. Image URLs must be publicly reachable. Internal network images require temporary public URLs or Base64 encoding.
  3. Reasoning mode limitations: Reasoning features are not universally supported. If responses degrade after enabling reasoning, toggle the switch off and compare outputs. When filling in context length limits, user prompts, tool definitions and chat history combine together, which easily triggers context_length_exceeded. Reduce history segments before increasing token ceilings.

Recommended three-stage rollback test: validate 4K, 16K and 64K context windows separately, observe the first-token latency and truncation behavior, then define appropriate upper limits.

models.json Troubleshooting Checklist: 10 Common Configuration Mistakes

Most ineffective custom model configurations are caused by minor syntax or path mistakes rather than architectural defects.

  1. File path distinction: User-level ~/.codebuddy/models.json vs project-level <workspace>/.codebuddy/models.json. Project configuration overrides user settings.
  2. JSON syntax validation: Run python3 -m json.tool to validate files. Trailing commas are the most frequent syntax error.
  3. Top-level array structure: The root node must contain the models array. Empty availableModels means exposing all available models, while non-empty lists filter visible options.
  4. Full reload requirement: Exit and restart the process after file edits. Hot reload triggers after 1 second, but unsaved disk changes cannot activate updates.
  5. URL normalization: Remove trailing slashes, avoid duplicated /v1 segments, and ensure paths end with /chat/completions.
  6. Valid id value: Pull model identifiers from the provider’s list API or official documentation before entering them in WorkBuddy.
  7. API key rules: The apiKey field holds real credentials, not variables. Never embed keys inside URL strings.
  8. Capability mapping: Set supportsToolCall, supportsImages, supportsReasoning according to actual model capabilities, instead of copying values from unrelated model templates.
  9. Duplicate entry merging: Entries with identical id overwrite previous definitions. Repeated entries may cause unexpected priority conflicts.
  10. Backup strategy: Create backups before modification. Rename old files such as models.json.bad for rollback when configuration breaks.
{
  "models": [
    {
      "id": "deepseek-chat",
      "name": "DeepSeek Chat",
      "vendor": "DeepSeek",
      "url": "https://api.deepseek.com/v1/chat/completions",
      "apiKey": "sk-your-key",
      "maxInputTokens": 32000,
      "maxOutputTokens": 4096
    }
  ]
}

Frequently Asked Questions

Q: Configuration saved successfully, but no model shows on the selector list

Validate JSON syntax and file path first. Confirm the id exists inside availableModels. Clear cache and perform a complete application restart. This issue is documented in WorkBuddy official fault resolution notes of 2026.

Q: The API works on other clients, but fails in WorkBuddy

Compare request headers, streaming flags, tool definition fields and authentication headers. Many compatible APIs only support plain text chat and omit fields required for Agent operations. When hybrid routing of multiple model endpoints is needed, Treerouter, an API gateway, can standardize request and response schemas across heterogeneous model services.

Q: Basic chat runs normally, Agent workflow crashes immediately

Disable tool calling and run tests with plain text prompts first. Some provider templates need dedicated conversion gateways to translate tool call schemas for WorkBuddy consumption.

Q: Image upload triggers HTTP 400 errors

Turn on vision capability switches for the target model. Run tests with minimal image_url payloads. Check URL accessibility, file size limits and timeout constraints.

Conclusion

Custom model integration failures follow a clear priority order: endpoint assembly, API key permissions, incomplete protocol translation and mismatched feature capabilities. This diagnostic system combines WorkBuddy official models.json specification and community-verified curl testing workflows. Developers can isolate faults rapidly by following the five-layer inspection pipeline, rather than randomly changing model names and parameters.

This article is written based on materials published in September 2026. Developers building production systems should refer to the latest official documentation for field definitions and protocol rules.

Learn more：https://treerouter.com