OpenClaw API-KEY Configuration

1. Course Content

This course will provide a detailed introduction to configuring AI model API-KEYs for OpenClaw, including the API-KEY application process, two configuration methods (CLI command configuration and configuration file modification), and how to verify successful configuration. After completing this course, you will be able to successfully connect and use various AI model service providers.

Course Objectives

• Understand the types of model service providers supported by OpenClaw

• Master the method for applying for API-KEY

• Learn how to view and verify the status of connected models

2. API-KEY Application

2.1 Recommended Model Service Providers

• Refer to the accompanying tutorial [AI Large Model Development] — [Register Model Service Account] for API-KEY application reference

• OpenClaw supports many model service providers, for example:

  • OpenAI

  • Alibaba Cloud - Tongyi Qianwen

  • DeepSeek

  • Zhipu AI

  • Moonshot

• You can freely choose a model service provider based on the network policies of your country and region, and register and apply for an API-KEY on the corresponding official website

3. Configure OpenClaw API-KEY

3.1 Configuration Methods

OpenClaw provides two methods for configuring API-KEY:

1. Desktop App Configuration (Recommended)

2. Direct Configuration File Modification (Suitable for developers)

3. Configuration file path: $HOME/.openclaw/openclaw.json

3.2 Quick Configuration

• Suitable for quick hands-on experience, first register for an Alibaba Cloud Bailian large model account and create an API-KEY (refer to the accompanying tutorial [AI Large Model Development] — [Register Model Service Account])

• The factory preset configuration file has already configured Bailian model parameters, just fill in the API-KEY and baseUrl to use directly

• Open the OpenClaw configuration file:

nano $HOME/.openclaw/openclaw.json
# For Raspberry Pi version:
nano $HOME/MODELS/openclaw/openclaw.json

3.2.1 Configure baseurl

• Users need to configure the baseUrl corresponding to their own account. Go to the Alibaba Cloud Model Studio Console, apply for API key, copy the API key and OpenAI-compatible address (Base URL), and fill in the corresponding positions.

3.2.2 Fill in apiKey and baseUrl

• Method 1: Open Desktop App Configuration

Double-click the desktop icon:

Find AI Large Models and Agents, fill in apiKey and baseUrl. The two positions can be the same. Visual large models can also separately fill in other OpenAI protocol-compatible visual models.

Click Save and Sync Configuration, then exit.

• Method 2: Find the corresponding field and replace baseurl and apiKey fields

  • Path: $HOME/.openclaw/openclaw.json

After filling in, press Ctrl+X, then press Y to confirm saving, and press Enter to exit.

4. View Connected Model Status

4.1 View Configured Model List

After configuration, you can use the following command to view the connected models:

​x
# For Raspberry Pi version, restart openclaw first
ocg restart
# For other boards
openclaw gateway restart

openclaw models list

4.2 Verify Configuration Success

1. Test Conversation

   xxxxxxxxxx
   openclaw tui
   

   Start the TUI interface, send a test message (such as "Hello"), and confirm the model can respond normally.

5. Other Connection Methods

• If you have your own model provider or need to connect to other model providers later, refer to the following tutorials

5.1 CLI Command Configuration (Suitable for Beginners)

1. Start Configuration Wizard

   xxxxxxxxxx
   openclaw onboard
   

• Select [Yes] and press Enter

• Select configuration mode as QuickStart and press Enter

2. Select Model Service Provider

   • Use up and down arrows to select the service provider for which you have applied for an API-KEY, press Enter to confirm. Here we take Alibaba Cloud Bailian model provider as an example. The configuration method for other model providers is the same.

   • Here select custom provider [Custom Provider]

• Fill in the base_url of the model service provider

3. Enter API-KEY

• After selecting a service provider, the system will prompt you to enter the corresponding API-KEY

• Paste or enter your applied API-KEY and press Enter to confirm

• Select interface protocol as OpenAI-compatible

4. Fill in the model name. Here we take MiniMax as an example.

• Endpoint ID is the model provider identifier, you can fill in freely

• Model alias (optional) can be left empty

5. Other Configuration

• For other configuration items, press as shown in the figure below to select all Skip, no configuration needed

• Press space to select Skip for now for Enable Hooks

• Select Restart to restart the gateway and apply the configuration

For Raspberry Pi version, use ocg restart instead.

5.2 Modify Configuration File (Recommended Method)

Configuration File Location

• The configuration file is located at: $HOME/.openclaw/openclaw.json

Edit Configuration File

xxxxxxxxxx
nano $HOME/.openclaw/openclaw.json
# Or use your favorite editor, such as vim, code, etc. It is recommended to modify through IDEs like vscode for easier operation

1. Add Model Provider Configuration

   Add or modify the models.providers section in the configuration file. Refer to the format below. You can refer to the factory default bailian provider's configuration format:

   xxxxxxxxxx
   {
     "models": {
       "providers": {
         "openai": {
           "apiKey": "OPENAI_API_KEY"
         },
         "anthropic": {
           "apiKey": "ANTHROPIC_API_KEY"
         },
         "google": {
           "apiKey": "GOOGLE_API_KEY"
         }
       }
     },
     "agents": {
       "defaults": {
         "model": {
           "primary": "openai/gpt-4"
         }
       }
     }
   }
   

3. Save and Exit

   • Press Ctrl+O to save, Ctrl+X to exit (nano editor)

4. Factory Default Bailian Configuration (Can be directly modified or referenced)

xxxxxxxxxx
  "bailian": {
    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "apiKey": "sk-a87e1137b17b4a35af13aaxxxxxxx",
    "api": "openai-completions",
    "models": [
      {
        "id": "qwen3.5-plus",
        "name": "qwen3.5-plus",
        "api": "openai-completions",
        "reasoning": false,
        "input": [
          "text",
          "image"
        ],
        "cost": {
          "input": 0,
          "output": 0,
          "cacheRead": 0,
          "cacheWrite": 0
        },
        "contextWindow": 1000000,
        "maxTokens": 65536
      },
      {
        "id": "qwen3.6-plus",
        "name": "qwen3.6-plus",
        "api": "openai-completions",
        "reasoning": false,
        "input": [
          "text",
          "image"
        ],
        "cost": {
          "input": 0,
          "output": 0,
          "cacheRead": 0,
          "cacheWrite": 0
        },
        "contextWindow": 1000000,
        "maxTokens": 65536
      },
      {
        "id": "qwen3-coder-next",
        "name": "qwen3-coder-next",
        "api": "openai-completions",
        "reasoning": false,
        "input": [
          "text"
        ],
        "cost": {
          "input": 0,
          "output": 0,
          "cacheRead": 0,
          "cacheWrite": 0
        },
        "contextWindow": 262144,
        "maxTokens": 65536
      },
      {
        "id": "MiniMax-M2.5",
        "name": "MiniMax-M2.5",
        "api": "openai-completions",
        "reasoning": false,
        "input": [
          "text"
        ],
        "cost": {
          "input": 0,
          "output": 0,
          "cacheRead": 0,
          "cacheWrite": 0
        },
        "contextWindow": 196608,
        "maxTokens": 32768
      },
      {
        "id": "glm-5",
        "name": "glm-5",
        "api": "openai-completions",
        "reasoning": false,
        "input": [
          "text"
        ],
        "cost": {
          "input": 0,
          "output": 0,
          "cacheRead": 0,
          "cacheWrite": 0
        },
        "contextWindow": 202752,
        "maxTokens": 16384,
        "compat": {
          "thinkingFormat": "qwen"
        }
      },
      {
        "id": "glm-4.7",
        "name": "glm-4.7",
        "api": "openai-completions",
        "reasoning": false,
        "input": [
          "text"
        ],
        "cost": {
          "input": 0,
          "output": 0,
          "cacheRead": 0,
          "cacheWrite": 0
        },
        "contextWindow": 202752,
        "maxTokens": 16384,
        "compat": {
          "thinkingFormat": "qwen"
        }
      },
      {
        "id": "kimi-k2.5",
        "name": "kimi-k2.5",
        "api": "openai-completions",
        "reasoning": false,
        "input": [
          "text",
          "image"
        ],
        "cost": {
          "input": 0,
          "output": 0,
          "cacheRead": 0,
          "cacheWrite": 0
        },
        "contextWindow": 262144,
        "maxTokens": 32768,
        "compat": {
          "thinkingFormat": "qwen"
        }
      }
    ]
  }

6. Common Problems and Solutions

Problem: After configuration, it prompts API-KEY is invalid or authentication failed

1. Confirm the API-KEY is correct (note there should be no extra spaces)

2. Check if the API-KEY has expired or been disabled

3. Confirm if the account balance is sufficient (some service providers require prepaid balance)

Problem: Configuration is correct but cannot connect to the model service

1. Check if the network connection is normal

2. Confirm if the network in your country/region can access the service

3. Try switching to another model service provider for testing