Custom Model Config

Overview

Manage custom AI model configurations for WorkBuddy by editing the ~/.workbuddy/models.json file. This skill enables adding OpenAI-compatible model providers (OpenAI, Anthropic-via-proxy, Kimi, Qwen/通义千问, DeepSeek, GLM/智谱, MiniMax, etc.), listing existing configurations, updating model settings, removing models, and validating configurations.

WorkBuddy loads custom models from ~/.workbuddy/models.json at startup and watches the file for live changes — no restart required. Custom models appear in the model selector prefixed with custom-local: (e.g., custom-local:gpt-5.4).

Configuration File

Path: ~/.workbuddy/models.json (on Windows: C:\Users\<username>\.workbuddy\models.json)

Format: JSON array of model objects. If the file does not exist, create it with an empty array [].

Model Object Schema

Each object in the array supports the following fields:

Example Configuration

[
  {
    "id": "gpt-5.4",
    "name": "GPT-5.4",
    "vendor": "OpenAI",
    "url": "https://api.openai.com/v1/chat/completions",
    "apiKey": "sk-xxxxxxxxxxxxxxxxxxxx",
    "supportsToolCall": true,
    "supportsImages": true,
    "supportsReasoning": true,
    "useCustomProtocol": false
  },
  {
    "id": "kimi-k2.6",
    "name": "Kimi K2.6",
    "vendor": "Kimi Coding Plan",
    "url": "https://api.kimi.com/coding/v1",
    "apiKey": "sk-xxxxxxxxxxxxxxxxxxxx",
    "supportsToolCall": true,
    "supportsImages": true,
    "supportsReasoning": true
  }
]

Workflow: Add a Custom Model

1. Read the existing ~/.workbuddy/models.json file. If it does not exist, initialize with [].
2. Collect the required information from the user:
   - Model ID: A unique identifier (e.g., gpt-5.4, deepseek-r1). Ask the user or infer from the provider/model name.
   - Display Name: Human-readable name for the selector UI.
   - Provider/Vendor: Which AI provider (OpenAI, DeepSeek, Kimi, Qwen, GLM, etc.).
   - API URL: The endpoint URL. Consult references/providers.md for common provider URLs, or ask the user for the exact endpoint.
   - API Key: The secret key. Never display the full key in the response — mask it (e.g., sk-xxxx...xxxx).
   - Capability flags: Whether the model supports tool calling, image inputs, and reasoning. Consult references/providers.md for known capabilities, or ask the user.
3. Construct the model object with all fields.
4. Check for duplicate id — if the ID already exists, ask the user whether to update or choose a new ID.
5. Append the new object to the array.
6. Write the updated JSON back to ~/.workbuddy/models.json with proper formatting (2-space indentation, UTF-8 encoding).
7. Inform the user that the model has been added and will appear as custom-local:<id> in the model selector. Changes take effect immediately (hot-reload).

Workflow: List Custom Models

1. Read ~/.workbuddy/models.json.
2. If the file does not exist or is empty, report that no custom models are configured.
3. Present each model in a readable format: ID, name, vendor, URL (masked API key), and capability flags.
4. Never display full API keys — always mask them as sk-xxxx...last4.

Workflow: Update a Custom Model

1. Read ~/.workbuddy/models.json.
2. Identify the model to update by id (ask the user which one if multiple exist).
3. Apply the requested changes (e.g., update API key, change URL, toggle capability flags).
4. Write the updated JSON back to the file.
5. Confirm the changes to the user.

Workflow: Remove a Custom Model

1. Read ~/.workbuddy/models.json.
2. Identify the model to remove by id.
3. Remove the object from the array.
4. Write the updated JSON back to the file.
5. Confirm removal to the user.

Workflow: Validate Configuration

Run the validation script to check configuration integrity:

python scripts/validate_models.py

The script checks:
- JSON syntax validity
- Required fields present for each model
- URL format correctness (must start with http:// or https://)
- API key presence and non-emptiness
- No duplicate model IDs
- Optional: API connectivity test (sends a minimal test request)

Pass --test-connection to also test API reachability:

python scripts/validate_models.py --test-connection

Security Guidelines

• API Key Handling: API keys are secrets. When displaying model configurations, always mask keys as sk-xxxx...last4. Never log full keys or include them in response text.
• File Permissions: The models.json file contains sensitive API keys. Do not share its contents publicly or commit it to version control.
• User Confirmation: Always confirm with the user before overwriting or removing existing model configurations.
• No Key Guessing: Never fabricate or guess API keys. Always obtain them from the user.

Common Provider Quick Reference

For detailed provider information (URLs, capability flags, notes), refer to references/providers.md. Common providers include:

Troubleshooting

• Model not appearing in selector: Verify models.json is valid JSON (run validation script). Check that the id field is unique and alphanumeric.
• API errors when using custom model: Verify the URL is correct and OpenAI-compatible. Check that the API key is valid and has sufficient credits. Some providers require specific URL paths.
• Tool calling not working: Ensure supportsToolCall is set to true. Not all models support function calling even if the API endpoint accepts the parameter.
• Reasoning/thinking mode not available: Ensure supportsReasoning is true and the model actually supports it (e.g., GPT-o1, DeepSeek-R1, Claude with extended thinking).
• Enterprise policy restrictions: In enterprise environments, custom model usage may be restricted by admin policy. If custom models are not available, check with the workspace administrator.