Model List

The model list manages Providers, model instances, default models, and model test results. Before configuring models, understand these concepts:

Configuration Item	Description	Example
Provider	Model service provider or access method, used to distinguish model sources	OpenAI Compatible, local model gateway, third-party model platform
Base URL	API access address for the model service	https://api.example.com/v1, http://127.0.0.1:8001/v1
API Key	Authentication credential required to call the model service	Third-party platform key, enterprise model gateway Token
Model Name	Actual model identifier used for calls; must match the server-side model ID	gpt-4.1, qwen2.5-72b-instruct
Default Model	Model used by sessions, Agents, tasks, and Workflows that do not specify a model	Default session model, default task model

After model configuration is complete, test the connection immediately and set a stable available model as the system default. Then new sessions, Agent runs, and Workflow executions can directly use verified model capabilities. For critical Agents, you can also specify a model on the Agent card so it does not follow system default model changes.

1. Recommended Models on the ThreatBook Model Platform

The ThreatBook model platform provides a recommended model Provider for Flocks: ThreatBook-cn-llm. Models in this Provider are organized in the model list according to Flocks runtime scenarios and are suitable as default models, task models, or sub-agent models.

Recommended models include:

Model ID	Context Length	Suitable Scenarios
minimax-m2.7	197K	Long-context analysis, complex tasks, main Agent default model.
minimax-m2.5	197K	General tasks, long sessions, stable default model.
GLM-5	200K	Reasoning, tool calling, comprehensive analysis tasks.
qwen3.6-plus	991K	Ultra-long-context tasks, large-scale log or alert analysis.
qwen3-max	252K	High-complexity reasoning, critical tasks, main Agent or important Workflow.
kimi-k2.6	256K	Long-text understanding, report organization, material summarization.
deepseek-v4-flash	128K	Response-speed priority and cost-sensitive routine tasks.
minimax-m3	128K	Sub-agents, lightweight tasks, daily Q&A, and tool assistance.

Usage recommendations:

• On first deployment of Flocks, select a stable model from ThreatBook-cn-llm as the system default model.
• The main Agent Rex should use a model with stronger reasoning and longer context, such as minimax-m2.7, GLM-5, qwen3-max, or qwen3.6-plus.
• Sub-agents can usually use lower-cost, faster-response models such as deepseek-v4-flash or minimax-m3.
• For long-input scenarios such as batch alerts, logs, and asset data, prefer models with larger context length.
• Even for recommended models, click Test Connection before setting them as default, and verify once with a real task.

2. Add a Model

For first-time configuration, this order is the most reliable:

1. Open the WebUI and go to Model List.
2. Click Add Model Provider at the top right and select the corresponding model provider. Local models usually use OpenAI Compatible.
3. Fill in Base URL and API Key.
4. Save the Provider configuration and close the Provider configuration window.
5. Click Add Model at the top right to add a specific model.
6. Fill in the model name. The model name must match the actual model ID on the server.
7. After saving, click Test Connection.
8. After the test passes, set this model as the default model.
9. Create a new session, send a simple question, and confirm Flocks replies normally.

After these steps, the model is truly usable. Saving the configuration without a passing test usually does not prove the system is connected.

3. Configure the System Default Model

The system default model is Flocks' baseline model selection. New sessions, Rex default execution, Agents without individually specified models, Task Center, and most Workflow nodes all prefer the default model configured here.

3.1 Set the Default Model on the Model List Page

Steps:

1. Open the WebUI and go to Model List.
2. Find the Default Model card at the top left of the page.
3. Click the edit button on the card.
4. In the dialog, select the Provider and model to use as the default.
5. Save, then confirm the Default Model card shows the new model name.

If the current default model is deleted, or its Provider is deleted, the system automatically clears the default model and you need to choose again.

3.2 What the Default Model Affects

The default model affects:

• The model used by Rex when creating new WebUI sessions.
• The default model used when creating tasks in Task Center.
• Agents without individually specified models.
• Model inference nodes or Agent nodes in Workflows where model is left empty.
• The default model used when new Sessions are created from IM channels.

Agents that have been manually assigned a model on the Agent card do not automatically switch when the system default model changes.

3.3 When to Adjust the Default Model

Adjust the system default model in these situations:

• First deployment is complete and you need to choose a stable model as the global entry point.
• The current default model fails, has high latency, or is too expensive.
• The team wants to switch uniformly to a new model Provider.
• Rex main sessions need stronger context, reasoning, or more stable tool calling.

The default model should be stable, have sufficient context, and perform reliably with tool calling. Cost-sensitive sub-agents can be configured separately with lighter models instead of downgrading the entire system default model.

4. Configure a Model for Each Agent

Each Agent can use the system default model or bind to a specific model. This configuration is completed on the Agent page.

4.1 Use the System Default Model

By default, an Agent's model selection is "System Default". This means:

• The Agent does not pin a Provider / model in its own configuration.
• Each run reads the current system default model from the model list page.
• When the system default model changes, this Agent automatically follows the new default model.

This approach is suitable for most ordinary Agents and makes unified model maintenance easier.

4.2 Specify a Model for a Single Agent

Steps:

1. Go to the Agent page.
2. Click the Agent card you want to adjust.
3. Find the Model field in the Agent details or edit panel.
4. Select the specific Provider / model from the model list.
5. Adjust temperature and other parameters as needed.
6. Save, then confirm the Agent card or details show the specified model.
7. Run a small task with this Agent and confirm the call works.

After a model is manually specified, this Agent continues using that model even if the system default model changes on the model list page. It follows the default model again only after you change the Agent's model back to "System Default".

4.3 When to Specify a Model for an Agent

Specify a model for an Agent in these scenarios:

• A critical Agent's output must stay stable and should not be affected by system default model changes.
• An Agent performs complex reasoning and needs a stronger model.
• An Agent has high task volume and should use a lower-cost or faster-response model.
• An Agent depends on a specific model's tool-calling stability.
• A sub-agent handles only a narrow-domain task and can use a medium or small model around 30B to reduce cost.

Model selection recommendations:

• The main Agent Rex must use the strongest available model. Prefer recommended models from the ThreatBook model platform. For locally self-hosted models, use a model larger than 200B parameters.
• Sub-agents can generally switch to smaller models. Depending on task complexity, choose 7B, 30B, or 70B-class models and balance quality, cost, and response speed.

4.4 Relationship Between Default Model and Agent-specific Model

Agent Model Configuration	After System Default Model Changes	Suitable Scenarios
System Default	Automatically follows the new default model	Ordinary Agents, temporary Agents, Agents managed centrally
Specific model	Does not change and continues using the specified model	Critical Agents, cost-optimized Agents, Agents with special model capability requirements

If you are unsure, keep "System Default" first. When a specific Agent needs separate optimization for quality, cost, speed, or tool-calling stability, specify a model for it.

5. How to Confirm Configuration Success

All of the following should be true:

• The Provider and model are visible in the model list.
• The model connection test passes.
• A default model has been set.
• New sessions can reply normally.
• Agents using the system default model can execute normally.
• Agents with individually specified models can execute normally, and the details show the specified model.

If a new session cannot reply normally, return to model name, context length, API Key, or model service connectivity troubleshooting.

6. Local and Third-party Model Integration

When integrating a local model, the model service needs to provide an OpenAI Compatible API. After deploying the model service, install and select the OpenAI Compatible Provider in Flocks. When adding the model, fill in the model name and context length according to the model's actual capabilities.

7. Model Error Troubleshooting

When troubleshooting model call exceptions, identify the failure scope first, then adjust configuration. Common failure scopes include Provider connection failures, a single unavailable model, and failures in complex task scenarios.

7.1 Check the Impact Scope First

Symptom	More Likely Problem	Next Step
All models fail	Provider, network, authentication, or gateway exception	Check Base URL, API Key, service status, and network connectivity
Only one model under the same Provider fails	Model name, model offline, insufficient permission	Verify the model ID and compare with another model under the same Provider
Test connection passes, but real tasks fail	Context, output length, or tool-calling compatibility	Retest with a short task, then increase complexity gradually
Context-length-related error	Configured context length exceeds what the model or gateway actually supports	Lower the model context parameter and test again
Simple Q&A works, long sessions fail	Context limit or insufficient model capability	Switch to a long-context model, reduce input length, or reduce output limit
Occasional timeout	Model platform load, network fluctuation, or reverse-proxy timeout	Check model service logs and proxy timeout configuration

7.2 Recommended Troubleshooting Order

1. Return to the model list page and click Test Connection again.
2. If all models fail, check the Provider first: Base URL, API Key, network, and model service status.
3. If only one model fails, check the model name and platform permissions first.
4. If new sessions fail, confirm the system default model has been set and is still in the available list.
5. If only one Agent fails, check whether that Agent has individually specified an unavailable model.
6. If tests pass but tasks fail, verify the session with a short question, then validate tool calling with a real task.
7. If failures occur only in complex tasks, check context length, max output, model capability, and server-side rate limits. Flocks recommends setting model context length to 128000 Token; if the model service does not support that length, manually lower the context parameter before testing again.
8. Check Flocks backend logs and model service logs to identify which layer produced the specific error.

7.3 Understanding Common Errors

Error or Symptom	Usual Meaning	Recommended Action
401 / 403	API Key is invalid or lacks permission	Regenerate the Key and confirm model permissions
404	Base URL path is wrong, or model name does not exist	Check whether /v1 is missing and verify the model ID
timeout	Service response is slow or network path is unstable	Reduce task complexity, check model service load and proxy timeout
empty content	Model service returned empty content or the compatibility layer is abnormal	Compare with another model and check model service logs
peer closed connection	Server actively closed the connection	Check model service status, gateway, and reverse-proxy configuration

7.4 Acceptance Recommendations

Before putting a model online, run at least three kinds of tests:

• Simple session: confirm basic Q&A returns.
• Longer analysis question: confirm context and output capacity are sufficient.
• Task with tools or a business scenario: confirm Flocks' real Workflow can run through.

Only after all three are stable should you use the model as the team's long-term default model.