OpenClaw Clawdbot Configuration Tutorial

OpenClaw is fully open-source. You can browse the source code, submit issues, or contribute on the OpenClaw GitHub Repository. This tutorial covers installation, configuration, and the complete steps to connect OpenClaw to Aurora API.

🌟 Core Features

Multi-channel Integration

• Multi-channel Integration: Supports various messaging channels including Telegram, Discord, WhatsApp, iMessage, and more via plugins
• Single Gateway: Unified management of all channels through a single Gateway process
• Voice Support: Supports voice interaction on macOS/iOS/Android
• Canvas Interface: Renders interactive Canvas UI

Self-hosting & Data Security

• Fully Self-hosted: Runs on your own machine or server
• Open Source & Transparent: MIT licensed with completely transparent code
• Local Data Storage: Context and skills stored on your local computer, not in the cloud

Intelligent Agent Capabilities

• Continuous Operation: Runs persistently in the background with long-term memory
• Scheduled Tasks: Supports cron scheduled tasks
• Session Isolation: Sessions isolated by agent/workspace/sender
• Multi-agent Routing: Supports collaborative multi-agent workflows
• Tool Calling: Native support for tool calls and code execution

📦 Pre-requisites

Before connecting to Aurora API, we recommend first getting the Gateway and Control UI running according to OpenClaw's official recommended process. This makes it easier to distinguish whether issues are due to OpenClaw not starting or model provider misconfiguration during troubleshooting.

1. Install OpenClaw (macOS/Linux)

curl -fsSL https://openclaw.ai/install.sh | bash

For other installation methods, refer to the official OpenClaw documentation：Getting Started。

2. Run the Onboarding Wizard

openclaw onboard --install-daemon

This wizard handles basic authentication, Gateway setup, and optional channel initialization. The goal is to get OpenClaw running first, then switch the default model to Aurora API later.

3. Check Gateway & Control UI

openclaw gateway status

openclaw dashboard

If the Control UI opens in your browser, OpenClaw is running correctly. You don't need to configure Telegram, Discord, or other message channels at this stage.

4. Locate the Configuration File

OpenClaw's configuration file is typically located at ~/.openclaw/openclaw.json. You can continue modifying the configuration generated by the onboarding wizard.。

🚀 Using Aurora API as a Model Provider

OpenClaw supports connecting to custom or OpenAI-compatible model gateways via models.providers. The most common approach for Aurora API is to add it as a custom provider and point the default model to newapi/model-id.

Integration Approach

1. Declare a newapi provider under models.providers.
2. Set baseUrl to your Aurora API address and ensure it includes /v1.
3. Set api to openai-completions.
4. List the model IDs that you want OpenClaw to use in models.
5. In agents.defaults.model.primary, change the default model to newapi/... `

Recommended approach: Store the key in an environment variable

First, provide your Aurora API key in the current shell, service environment, or in the .env file that OpenClaw can read:

export NEWAPI_API_KEY="sk-your-newapi-key"

Then, in the openclaw.json file, add or modify the following section:

{
  models: {
    mode: "merge",
    providers: {
      newapi: {
        baseUrl: "https://<your-newapi-domain>/v1",
        apiKey: "${NEWAPI_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gemini-2.5-flash", name: "Gemini 2.5 Flash" },
          { id: "kimi-k2.5", name: "Kimi K2.5" },
        ],
      },
    },
  },

  agents: {
    defaults: {
      model: {
        primary: "newapi/gemini-2.5-flash",
        fallbacks: ["newapi/kimi-k2.5"],
      },
      models: {
        "newapi/gemini-2.5-flash": { alias: "flash" },
        "newapi/kimi-k2.5": { alias: "kimi" },
      },
    },
  },
}

This is not a complete configuration that must be copied exactly as it is. Instead, it is the most crucial part for integrating with the Aurora API. As long as the provider, model ID, and default model reference are all correctly matched, OpenClaw will be able to call the model resources you expose through the Aurora API.

Key Configuration Instructions

| Configuration Item | Description | | --- | --- | | models.mode | Suggest setting it to merge, while retaining the built-in provider of OpenClaw and adding newapi | | models.providers.newapi.baseUrl | Your Aurora API address, usually requiring the /v1 suffix | | models.providers.newapi.apiKey | Aurora API key, recommended to be injected via ${NEWAPI_API_KEY} | | models.providers.newapi.api | For OpenAI-compatible gateways like Aurora API, use openai-completions | | models.providers.newapi.models | The listed model IDs here must match the actual exposed model names of your Aurora API | | agents.defaults.model.primary | Default primary model, the format must be provider/model-id | | agents.defaults.model.fallbacks | List of alternative models, automatically switches when the primary model fails | | agents.defaults.models | Optional, used to give aliases to models for easier reference in UI or conversations | Verify whether the connection has been successful After completing the configuration, return to the Control UI or reopen it:

openclaw dashboard

If you can initiate a conversation normally in OpenClaw and the default model has changed to newapi/..., it indicates that the connection has been successful. You can also use:

openclaw models list

Confirm that the models with the newapi/ prefix have already appeared in the optional list.

Frequently Asked Questions

• baseUrl without /v1: This is one of the most common access errors.
• Incorrect model ID: primary and fallbacks must correspond to the id in models.providers.newapi.models.
• Key only valid in the current terminal: If the Gateway is running as a background service, make sure the service process can also read NEWAPI_API_KEY.
• Want to troubleshoot on the front end: You can use the official front-end running method openclaw gateway --port 18789 to observe logs and errors.