Model Configuration

Configure LLM providers using the new model_list format

Overview

PicoClaw uses a model-centric configuration approach that allows you to add new providers with zero code changes. Simply specify the vendor/model format (e.g., zhipu/glm-4.7) to configure any OpenAI-compatible provider.

This design enables:

• Multiple model providers in a single config
• Model fallbacks for resilience
• Load balancing across multiple endpoints
• Zero-code provider addition for OpenAI-compatible APIs

Configuration Format

Basic Structure

{
  "model_list": [
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "sk-your-key",
      "api_base": "https://api.openai.com/v1",
      "request_timeout": 300
    }
  ],
  "agents": {
    "defaults": {
      "model_name": "gpt4"
    }
  }
}

Field Definitions

model_name (required)

Type: string

User-facing alias for the model. This is what you reference in agents.defaults.model_name.

{
  "model_name": "my-gpt4"
}

model (required)

Type: string
Format: protocol/model-identifier

The protocol prefix and model identifier:

{
  "model": "openai/gpt-5.2"
}

Supported protocols:

• openai/ - OpenAI API
• anthropic/ - Anthropic Claude API
• zhipu/ - Zhipu GLM
• deepseek/ - DeepSeek
• gemini/ - Google Gemini
• groq/ - Groq
• qwen/ - Alibaba Qwen
• moonshot/ - Moonshot AI
• nvidia/ - NVIDIA
• cerebras/ - Cerebras
• ollama/ - Ollama (local)
• openrouter/ - OpenRouter
• litellm/ - LiteLLM Proxy
• vllm/ - vLLM
• volcengine/ - Volcengine (Doubao)
• shengsuanyun/ - ShengsuanYun
• mistral/ - Mistral AI
• github-copilot/ - GitHub Copilot
• antigravity/ - Google Cloud Code Assist

api_key

Type: string

API authentication key for the provider.

{
  "api_key": "sk-proj-..."
}

For local models (Ollama, vLLM) or OAuth-based providers (GitHub Copilot, Antigravity), api_key may not be required.

api_base

Type: string

Base URL for the API endpoint. If omitted, uses the provider’s default endpoint.

{
  "api_base": "https://api.openai.com/v1"
}

request_timeout

Type: integer (seconds)
Default: 120

Timeout for API requests in seconds.

{
  "request_timeout": 300
}

proxy

Type: string

HTTP proxy URL for the provider.

{
  "proxy": "http://proxy.example.com:8080"
}

auth_method

Type: string
Values: oauth, token

Authentication method for special providers (GitHub Copilot, Antigravity).

{
  "auth_method": "oauth"
}

connect_mode

Type: string
Values: stdio, grpc

Connection mode for GitHub Copilot.

{
  "connect_mode": "grpc"
}

Provider Examples

OpenAI

{
  "model_name": "gpt-5.2",
  "model": "openai/gpt-5.2",
  "api_key": "sk-proj-...",
  "api_base": "https://api.openai.com/v1"
}

Anthropic Claude

{
  "model_name": "claude-sonnet-4.6",
  "model": "anthropic/claude-sonnet-4.6",
  "api_key": "sk-ant-...",
  "api_base": "https://api.anthropic.com/v1"
}

Zhipu AI (智谱)

{
  "model_name": "glm-4.7",
  "model": "zhipu/glm-4.7",
  "api_key": "your-zhipu-key",
  "api_base": "https://open.bigmodel.cn/api/paas/v4"
}

Get API Key

DeepSeek

{
  "model_name": "deepseek-chat",
  "model": "deepseek/deepseek-chat",
  "api_key": "sk-...",
  "api_base": "https://api.deepseek.com/v1"
}

Get API Key

Google Gemini

{
  "model_name": "gemini-2.0-flash",
  "model": "gemini/gemini-2.0-flash-exp",
  "api_key": "AIza...",
  "api_base": "https://generativelanguage.googleapis.com/v1beta"
}

Get API Key

Qwen (通义千问)

{
  "model_name": "qwen-plus",
  "model": "qwen/qwen-plus",
  "api_key": "sk-...",
  "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1"
}

Get API Key

Groq

{
  "model_name": "llama-3.3-70b",
  "model": "groq/llama-3.3-70b-versatile",
  "api_key": "gsk_...",
  "api_base": "https://api.groq.com/openai/v1"
}

Get API Key

Ollama (Local)

{
  "model_name": "llama3",
  "model": "ollama/llama3",
  "api_base": "http://localhost:11434/v1",
  "api_key": "ollama"
}

No API key needed for local Ollama.

OpenRouter

{
  "model_name": "openrouter-auto",
  "model": "openrouter/auto",
  "api_key": "sk-or-v1-...",
  "api_base": "https://openrouter.ai/api/v1"
}

Get API Key

LiteLLM Proxy

{
  "model_name": "lite-gpt4",
  "model": "litellm/lite-gpt4",
  "api_key": "sk-...",
  "api_base": "http://localhost:4000/v1"
}

PicoClaw strips only the outer litellm/ prefix. So litellm/lite-gpt4 sends lite-gpt4, while litellm/openai/gpt-5.2 sends openai/gpt-5.2 to your proxy.

Custom OpenAI-Compatible API

{
  "model_name": "my-custom-model",
  "model": "openai/custom-model-v1",
  "api_key": "custom-key",
  "api_base": "https://my-api.example.com/v1",
  "request_timeout": 300
}

Load Balancing

Configure multiple endpoints with the same model_name for automatic round-robin load balancing:

{
  "model_list": [
    {
      "model_name": "gpt-5.2",
      "model": "openai/gpt-5.2",
      "api_base": "https://api1.example.com/v1",
      "api_key": "sk-key1"
    },
    {
      "model_name": "gpt-5.2",
      "model": "openai/gpt-5.2",
      "api_base": "https://api2.example.com/v1",
      "api_key": "sk-key2"
    }
  ]
}

PicoClaw automatically distributes requests across both endpoints.

Multiple Models

Configure multiple models and select between them:

{
  "model_list": [
    {
      "model_name": "gpt-5.2",
      "model": "openai/gpt-5.2",
      "api_key": "sk-openai-key"
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4.6",
      "api_key": "sk-ant-key"
    },
    {
      "model_name": "gemini-flash",
      "model": "gemini/gemini-2.0-flash-exp",
      "api_key": "AIza-key"
    }
  ],
  "agents": {
    "defaults": {
      "model_name": "claude-sonnet-4.6",
      "model_fallbacks": ["gpt-5.2", "gemini-flash"]
    }
  }
}

All Supported Providers

Provider	Prefix	Default API Base	Get API Key
OpenAI	openai/	https://api.openai.com/v1	Get Key
Anthropic	anthropic/	https://api.anthropic.com/v1	Get Key
Zhipu (智谱)	zhipu/	https://open.bigmodel.cn/api/paas/v4	Get Key
DeepSeek	deepseek/	https://api.deepseek.com/v1	Get Key
Gemini	gemini/	https://generativelanguage.googleapis.com/v1beta	Get Key
Groq	groq/	https://api.groq.com/openai/v1	Get Key
Qwen (千问)	qwen/	https://dashscope.aliyuncs.com/compatible-mode/v1	Get Key
Moonshot	moonshot/	https://api.moonshot.cn/v1	Get Key
NVIDIA	nvidia/	https://integrate.api.nvidia.com/v1	Get Key
Ollama	ollama/	http://localhost:11434/v1	Local (no key)
OpenRouter	openrouter/	https://openrouter.ai/api/v1	Get Key
LiteLLM	litellm/	http://localhost:4000/v1	Your proxy key
vLLM	vllm/	http://localhost:8000/v1	Local
Cerebras	cerebras/	https://api.cerebras.ai/v1	Get Key
Volcengine	volcengine/	https://ark.cn-beijing.volces.com/api/v3	Get Key
ShengsuanYun	shengsuanyun/	https://api.shengsuanyun.com/v1	-
Mistral	mistral/	https://api.mistral.ai/v1	Get Key
GitHub Copilot	github-copilot/	localhost:4321	OAuth
Antigravity	antigravity/	Google Cloud	OAuth

Migration from Legacy Config

If you’re using the old providers config format, see Legacy Providers Configuration for migration instructions.

Next Steps

• Configure Agent Defaults
• Legacy Providers Config
• Configure Tools