OpenClaw - Self-hosted AI Assistant Platform

OpenClaw is completely open-source. You can browse the source code, submit issues, or contribute on OpenClaw's GitHub repository. This tutorial covers the complete steps for installing, configuring, and integrating OpenClaw with New API.

🌟 Core Features

Multi-channel Integration

• Multi-channel Integration: Supports various messaging channels like Telegram, Discord, WhatsApp, iMessage, and can be extended to more platforms via plugins.
• Single Gateway: Unified management of all channels through a single Gateway process.
• Voice Support: Supports macOS/iOS/Android voice interaction.
• Canvas Interface: Can render interactive Canvas interfaces.

Self-hosting and Data Security

• Fully Self-hosted: Runs on your own machine or server.
• Open Source Transparency: MIT open-source license, completely transparent code.
• Local Data: Context and skills are stored on your local computer, not in the cloud.

Intelligent Agent Capabilities

• Continuous Operation: Supports persistent background operation with long-term memory.
• Scheduled Tasks: Supports cron scheduled tasks.
• Session Isolation: Isolates sessions by agent/workspace/sender.
• Multi-agent Routing: Supports collaborative work among multiple agents.
• Tool Calling: Native support for tool calling and code execution.

📦 Preparation Before Integration

Before integrating New API, it's recommended to first get the Gateway and Control UI running according to OpenClaw's official current recommended process. This makes it easier to distinguish whether OpenClaw itself is not starting or if the model provider configuration is incorrect when troubleshooting later.

1. Install OpenClaw (macOS/Linux)

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

For other installation methods, refer to the OpenClaw official documentation: Getting Started.

2. Run the Onboarding Wizard

openclaw onboard --install-daemon

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

3. Check Gateway and Control UI

openclaw gateway status

openclaw dashboard

If the browser can open the Control UI, it means OpenClaw's basic operation is normal. At this stage, there's no need to configure Telegram, Discord, Feishu, or other messaging channels yet.

4. Locate the Configuration File

OpenClaw's configuration file is usually located at ~/.openclaw/openclaw.json. You can continue to modify it based on what the onboarding wizard generated.

🚀 Using New API as a Model Provider

OpenClaw supports integrating custom or OpenAI-compatible model gateways via models.providers. For New API, the most common approach is to add it as a custom provider to the configuration, then point the default model to newapi/model-ID.

Integration Approach

1. Declare a newapi provider under models.providers.
2. Point baseUrl to your New API address, ensuring it includes /v1.
3. Set api to openai-completions.
4. List the model IDs you want OpenClaw to use in models.
5. Switch the default model in agents.defaults.model.primary to newapi/....

Recommended Practice: Store API Key in Environment Variables

First, provide your New API key in the current shell, service environment, or an .env file readable by OpenClaw:

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

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

{
  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, but rather the most critical part for integrating New API. As long as the provider, model IDs, and default model references are correct, OpenClaw will be able to call your exposed model resources via New API.

Key Configuration Details

Verify Successful Integration

After completing the configuration, return to the Control UI or reopen it:

openclaw dashboard

If you can initiate conversations normally in OpenClaw and the default model has become newapi/..., then the integration is successful. You can also use:

openclaw models list

to confirm that models with the newapi/ prefix appear in the selectable list.

Common Issues

• baseUrl missing /v1: This is one of the most common integration errors.
• Incorrect model ID: primary and fallbacks must correspond to the id in models.providers.newapi.models.
• API key only effective in the current terminal: If Gateway runs as a background service, ensure the service process can also read NEWAPI_API_KEY.
• For foreground troubleshooting: Use the official foreground running method openclaw gateway --port 18789 to observe logs and errors.