Model Configuration Guide

A Model in Wegent defines the AI model configuration, specifying which AI service to use, how to authenticate, and which model to employ. This guide will help you configure models through the Web interface.

📋 Table of Contents

What is a Model
Model Selection Guide
Configuring Models via Web Interface
API Key Acquisition
Testing Model Connection
Using Models in Bots
Frequently Asked Questions

🎯 What is a Model

A Model is the "brain" of a Bot, determining which AI model the Bot uses for thinking and reasoning.

Position in Architecture

Agent (Team) = Bot(s) + Collaboration Mode
Bot = Executor (Shell) + Model (Brain) + Prompt (Personality)

Analogy:

Executor (Shell): The runtime environment (ClaudeCode, Agno, Dify, Chat)
Model: The AI brain (Claude, GPT-4, Gemini)
Prompt: The personality and expertise

Model Types

Wegent supports multiple model types:

Type	Description	Use Cases
LLM	Large Language Models for chat and code	General AI tasks, coding
Embedding	Text embedding models	Knowledge base, RAG
Rerank	Reranking models	Search result optimization

📊 Model Selection Guide

Anthropic Claude Series (Recommended for Code)

Model	Speed	Cost	Capability	Best For
Claude Haiku 4.5	⚡⚡⚡ Fast	💰 Low	⭐⭐ Basic	Simple tasks, documentation
Claude Sonnet 4	⚡⚡ Medium	💰💰 Medium	⭐⭐⭐⭐ Strong	Daily development (Recommended)
Claude Opus 4	⚡ Slow	💰💰💰 High	⭐⭐⭐⭐⭐ Strongest	Complex architecture

OpenAI GPT Series

Model	Speed	Cost	Capability	Best For
GPT-4o	⚡⚡ Medium	💰💰 Medium	⭐⭐⭐⭐ Strong	General tasks (Recommended)
GPT-4 Turbo	⚡⚡ Medium	💰💰 Medium	⭐⭐⭐⭐ Strong	Complex reasoning
GPT-3.5 Turbo	⚡⚡⚡ Fast	💰 Low	⭐⭐⭐ Medium	Quick prototyping

Google Gemini Series

Model	Speed	Cost	Capability	Best For
Gemini 3 Pro	⚡⚡ Medium	💰💰 Medium	⭐⭐⭐⭐ Strong	Multimodal tasks
Gemini 2.5 Flash	⚡⚡⚡ Fast	💰 Low	⭐⭐⭐ Medium	Quick responses

Recommendations by Task Type

Task Type	Recommended Model	Alternative
Daily Development	Claude Sonnet 4	GPT-4o
Simple Tasks	Claude Haiku 4.5	GPT-3.5 Turbo
Code Review	Claude Sonnet 4	GPT-4o
Complex Architecture	Claude Opus 4	GPT-4
Documentation	Claude Haiku 4.5	GPT-3.5 Turbo

🚀 Configuring Models via Web Interface

Step 1: Navigate to Model Settings

Log in to Wegent Web interface
Click Settings in the sidebar
Select the Models tab

You'll see a unified model list showing both public (system) and your personal models.

Step 2: Create a New Model

Click the Create Model button
Fill in the model configuration form:

Basic Information

Field	Required	Description
Model Type	Yes	Select: LLM, Embedding, or Rerank
Model ID	Yes	Unique identifier (lowercase, hyphens allowed)
Display Name	No	Human-readable name for the UI

Provider Configuration

Field	Required	Description
Model Protocol	Yes	OpenAI, Anthropic, Gemini, etc.
Model ID	Yes	Select from presets or enter custom
API Key	Yes	Your API key from the provider
Base URL	No	Custom endpoint (for proxies)

Step 3: Configure Model Details

For LLM Models:

Model Protocol: OpenAI / Anthropic / Gemini
Model ID: gpt-4o / claude-sonnet-4 / gemini-3-pro
API Key: sk-xxx... / sk-ant-xxx...
Base URL: (optional, for proxy services)

For Embedding Models:

Model Protocol: OpenAI / Cohere / Jina
Model ID: text-embedding-3-small
Dimensions: 1536 (optional)

For Rerank Models:

Model Protocol: Cohere / Jina
Model ID: rerank-english-v3.0
Top N: 10 (optional)

Step 4: Test Connection

Before saving, click Test Connection to verify:

✅ API Key validity
✅ Model availability
✅ Network connectivity

Step 5: Save Configuration

Click Save to create the model. It will appear in your model list and can be used in Bot configurations.

🔑 API Key Acquisition

Anthropic API Key

Visit Anthropic Console
Log in or create an account
Click Create Key
Copy and save the key (format: sk-ant-api03-xxx...)

⚠️ Important: API Key is only shown once!

OpenAI API Key

Visit OpenAI Platform
Log in or create an account
Click Create new secret key
Copy and save the key (format: sk-xxx...)

Google Gemini API Key

Visit Google AI Studio
Log in with your Google account
Click Create API Key
Copy and save the key (format: AIza...)

Security Best Practices

✅ Do:

Store keys in environment variables
Use key management services for production
Rotate keys regularly
Limit access to authorized team members

❌ Don't:

Commit keys to Git repositories
Share keys in public places
Write keys in frontend code
Store keys in plain text files

🔄 Testing Model Connection

Via Web Interface

In the Model Edit dialog, fill in all required fields
Click the Test Connection button
Check the result:
- ✅ "Successfully connected" - Configuration is valid
- ❌ Error message - Check your settings

Common Test Errors

Error	Cause	Solution
401 Unauthorized	Invalid API Key	Regenerate and update key
404 Not Found	Wrong model ID	Check model name spelling
429 Rate Limit	Too many requests	Wait and retry
Network Error	Connection issue	Check network/proxy settings

🤖 Using Models in Bots

When creating or editing a Bot:

In the Bind Model section, keep "Advanced Mode" OFF
Select a model from the dropdown list
The dropdown shows both public and your personal models

Method 2: Advanced Mode (Custom Configuration)

For custom model configurations:

Toggle Advanced Mode ON
Select the Model Protocol (OpenAI/Claude/Gemini)
Enter the JSON configuration:

{
  "env": {
    "model": "openai",
    "model_id": "gpt-4o",
    "api_key": "sk-xxx...",
    "base_url": "https://api.openai.com/v1"
  }
}

Per-Task Model Override

When sending a task, you can override the Bot's default model:

In the chat input area, click the Model selector
Choose a different model
Optionally enable Force Override to ensure your selection is used

⚠️ Frequently Asked Questions

Q1: What's the difference between public and personal models?

Type	Description	Visibility
Public	System-provided models	All users
Personal	Your custom configurations	Only you

Personal models take priority when names conflict.

Q2: How do I use a proxy service?

Set the Base URL field to your proxy endpoint:

OpenRouter: https://openrouter.ai/api/v1
Custom Proxy: https://your-proxy.example.com

Check:

Model status is "Available"
Model type matches the executor (e.g., Anthropic for ClaudeCode)
Model is an LLM type (not Embedding/Rerank)

Q4: How do I control costs?

Strategy 1: Use appropriate models

Simple tasks → Claude Haiku / GPT-3.5
Complex tasks → Claude Sonnet / GPT-4o

Strategy 2: Set usage limits

Configure limits in your API provider's console
Monitor usage regularly

Q5: Can I use the same API key for multiple models?

Yes! You can create multiple model configurations with the same API key but different model IDs.

Next Steps

Agent Settings - Configure agents and bots with models

Reference

💬 Get Help

Need assistance?

📖 Check FAQ
🐛 Submit GitHub Issue
💬 Join community discussions

Configure your models and power up your AI agents! 🚀

📋 Table of Contents​

🎯 What is a Model​

Position in Architecture​

Model Types​

📊 Model Selection Guide​

Anthropic Claude Series (Recommended for Code)​

OpenAI GPT Series​

Google Gemini Series​

Recommendations by Task Type​

🚀 Configuring Models via Web Interface​

Step 1: Navigate to Model Settings​

Step 2: Create a New Model​

Basic Information​

Provider Configuration​

Step 3: Configure Model Details​

Step 4: Test Connection​

Step 5: Save Configuration​

🔑 API Key Acquisition​

Anthropic API Key​

OpenAI API Key​

Google Gemini API Key​

Security Best Practices​

🔄 Testing Model Connection​

Via Web Interface​

Common Test Errors​

🤖 Using Models in Bots​

Method 1: Select from Dropdown (Recommended)​

Method 2: Advanced Mode (Custom Configuration)​

Per-Task Model Override​

⚠️ Frequently Asked Questions​

Q1: What's the difference between public and personal models?​

Q2: How do I use a proxy service?​

Q3: Why can't I see my model in the Bot dropdown?​

Q4: How do I control costs?​

Q5: Can I use the same API key for multiple models?​

🔗 Related Resources​

Next Steps​

Reference​

💬 Get Help​