Skip to main content

​
OpenClaw Model Configuration Guide

​
1. Overview

This guide explains how to configure a custom model provider in OpenClaw. After the configuration is complete, OpenClaw can call models through the specified API endpoint and use them for local Agent tasks.

​
2. Prerequisites

Before you start, make sure you have the following:
  1. OpenClaw installed on your device.
  2. A valid API Key.
  3. The model name you want to use.
  4. A network environment that can access the API service normally.

​
3. Open Terminal or Console

Open a terminal or command-line tool on your local device. macOS or Linux users can use Terminal. Windows users can use Command Prompt, PowerShell, or the terminal inside their development environment.

​
4. Open the OpenClaw Configuration Interface

Run the following command in the terminal: 
openclaw config
Press Enter to enter the configuration process.

​
5. Select Local Configuration

In the configuration menu, select:
text
Local
Press Enter. This option means the configuration will be applied to your local OpenClaw environment.

​
6. Enter Model Configuration

Continue by selecting:
text
Model
Press Enter. This option is used to configure the model service used by OpenClaw.

​
7. Select Custom Provider

Select:
text
Custom Provider
Press Enter. Choose this option when you want to connect OpenClaw to a custom OpenAI-Compatible API service.

​
8. Configure the API Base URL

When prompted to enter the API Base URL, input:
text
https://apihub.agnes-ai.com/v1
Press Enter. This address tells OpenClaw to send model requests to the Agnes AI API Gateway.

​
9. Enter the API Key

When prompted to enter the API Key, input your actual API Key. Example:
text
YOUR_API_KEY
In most cases, you do not need to manually add the Bearer prefix unless OpenClaw explicitly asks you to enter the full Authorization Header.

​
10. Enter the Model Name

When prompted to enter the model name, input the model ID you want to use. Example:
text
agnes-2.0-flash
Make sure to enter the full model ID provided by the platform.

​
11. Save the Configuration

After completing all required fields, confirm and save the configuration. Once saved successfully, OpenClaw will use this custom provider for local model calls.

​
12. Configuration Example

text
Provider Type: Custom Provider
API Base URL: https://apihub.agnes-ai.com/v1
API Key: YOUR_API_KEY
Model: agnes-2.0-flash

​
13. Verify the Configuration

After completing the configuration, you can run an OpenClaw task or start a test session. If the configuration is correct, OpenClaw should be able to send requests to the API service and return model responses normally.

​
14. Troubleshooting

​
1. API Request Failed

Check whether the API Base URL is correct:
text
https://apihub.agnes-ai.com/v1
Also confirm that your API Key is valid.

​
2. Model Not Found

Check whether the model name is entered correctly. Model IDs are usually case-sensitive. It is recommended to copy the model name directly from the platform.

​
3. Authentication Failed

Check whether the API Key has expired, whether the account has sufficient balance, and whether the Key has permission to access the target model.

​
4. Network Error

Make sure your device can access the API address normally. If the request cannot be completed, check your firewall, proxy, or VPN settings.

​
15. Notes

For OpenAI-Compatible API services, the API Base URL usually ends with /v1. Correct example:
text
https://apihub.agnes-ai.com/v1
It is usually not recommended to enter:
text
https://apihub.agnes-ai.com/v1/chat/completions
unless OpenClaw explicitly asks you to enter the full API endpoint.