OpenClaw Setup: Install and Use a Custom OpenAI Endpoint

OpenClaw is an open-source AI assistant. It combines conversations, a Gateway, channel integrations, tools and installable skills in one self-hosted workflow. You can run the Gateway in your own environment and let different chat entry points share the same set of agent settings.

As of 2026-09-21, the official npm package version is 2026.9.5. This article summarizes installation, minimal startup, model configuration and basic ClawHub operations based on the official documentation. If your version is different, follow the official documentation for that version.

1. What is OpenClaw, and what problem does it solve?

If you only want to ask a model questions in a terminal, a single SDK is enough. But when you want to put the same assistant into multiple chat entry points, have the Gateway manage it continuously, and extend workflows with skills, scattered settings quickly become hard to maintain.

The core of OpenClaw can be understood as follows:

• The Gateway is a resident control plane that receives requests and manages agent workflows.
• The agent decides which model to use and which defaults to apply.
• The provider configures how the model is connected, its API shape and its capabilities.
• A skill is a feature package that OpenClaw can use; ClawHub is the public skill registry.

This article covers only one minimal path: first get the Gateway running locally, then point the agent at an OpenAI-compatible endpoint. Further configuration of channels, the daemon and skills can be added after the basic path is confirmed.

2. Installation and a minimal working example

Prepare Node.js first

The official Getting Started documentation currently requires Node.js 24.16+ or 26.1+, and recommends Node 26. Check the versions first:

node --version
npm --version

Install OpenClaw

The official documentation provides an interactive installer; you can also install globally with npm:

npm install -g openclaw@latest --allow-scripts=openclaw

After installation, complete onboarding first:

openclaw onboard --install-daemon

If you do not want to install the daemon at the start, you can run:

openclaw onboard

Then start or check the Gateway:

openclaw gateway status
openclaw gateway

The official default Gateway port is 18789. To open the control interface, run:

openclaw dashboard

If you only want to confirm that the CLI can be found, this minimal check is enough:

openclaw --version

Look at skills with built-in commands first

The official OpenClaw documentation provides command-line examples for ClawHub:

openclaw skills search "calendar"
openclaw skills install @openclaw/demo
openclaw skills update --all

The point here is to first confirm that the CLI, the Gateway and the skill path all work. This article does not assume you have installed any particular skill.

3. Core configuration: point to a custom OpenAI-compatible endpoint

OpenClaw's official custom provider settings go under models.providers in the configuration file. A minimal JSON5 example looks like this:

{
  models: {
    providers: {
      bazaarlink: {
        baseUrl: "https://api.bazaarlink.ai/v1",
        apiKey: "${BAZAARLINK_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "gemini-3.8-flash",
            name: "gemini-3.8-flash",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 1000000,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "bazaarlink/gemini-3.8-flash",
      },
    },
  },
}

The gemini-3.8-flash used above is the actual model ID found when the public model list was read on 2026-09-21. This time, a request using the OpenAI-compatible image_url data URI shape returned 200 in testing, and the model did read the image and answer with its color; therefore the example declares the text and image inputs as verified, with the verification date of 2026-09-21.

Do not write the API key directly into version control. You can first set the environment variable that the placeholder maps to in the current shell:

export BAZAARLINK_API_KEY="<BAZAARLINK_API_KEY>"

Windows PowerShell:

$env:BAZAARLINK_API_KEY = "<BAZAARLINK_API_KEY>"

The key fields in the official custom provider documentation are:

• baseUrl: the base URL of the compatible endpoint.
• apiKey: can be replaced with an environment variable value.
• api: the API shape; the official example uses openai-completions for the OpenAI-compatible completion interface.
• models[].id: the model ID that the upstream actually accepts.
• reasoning, input, contextWindow, maxTokens: fields describing the model's capabilities and limits.
• agents.defaults.model.primary: specifies the default model in provider/model format.

If you want to keep other settings for a provider with the same name, the official documentation also describes the use of mode: "merge". When adding a new provider, it is easier to troubleshoot with a minimal configuration first:

{
  models: {
    mode: "merge",
    providers: {
      bazaarlink: {
        baseUrl: "https://api.bazaarlink.ai/v1",
        apiKey: "${BAZAARLINK_API_KEY}",
        api: "openai-completions",
        models: [{ id: "gemini-3.8-flash", name: "gemini-3.8-flash" }],
      },
    },
  },
}

The OpenClaw official documentation confirms the custom provider fields and how models are selected. Below is a minimal request-shape replay using a real account on 2026-09-21:

• GET https://api.bazaarlink.ai/v1/models with Authorization: Bearer returned 200; the response includes object and data, and the list includes gemini-3.8-flash.
• This configuration explicitly lists the model ID in models[], so the fixed-model generation path does not need to call /v1/models first to build the request. Catalog refresh such as openclaw models list --refresh is a separate flow and may read the model list separately.
• OpenClaw's openai-completions POST https://api.bazaarlink.ai/v1/chat/completions with stream: true returned 200 as text/event-stream, with 5 SSE chunks in total; it had text delta values and ended with [DONE]. A plain text conversation also returned 200, with finish_reason=stop and normal text.
• A request with tools and tool_choice: auto returned 200 with finish_reason=tool_calls; the response included get_weather and {"city":"Taipei"}. This confirmed that the standard OpenAI tool call finish reason was met.
• A request with the standard top-level reasoning_effort: "low" returned 200, but the response contained only role and content, with no structured reasoning field. This shows the request was accepted; it is not proof of full reasoning interoperability.
• A request using the image_url data URI commonly used by agents returned 200, and the model did read the image and answer with its color. This image input shape was verified on 2026-09-21.
• If the custom provider is explicitly changed to the Anthropic Messages shape, a short text request to POST /v1/messages with x-api-key returned 200 with type=message. This is not the default path for the current openai-completions configuration, and Anthropic-format tool and streaming interoperability has not been verified.

These are endpoint-level request-shape results, not a full acceptance test of an installed OpenClaw Gateway. Gateway sessions, channels and skill workflows still need to be verified separately.

4. Common issues

No model found after startup

First check whether agents.defaults.model.primary is in provider/model format, for example bazaarlink/gemini-3.8-flash. Then confirm that models.providers.bazaarlink.models[].id exactly matches an ID in the public model list.

Why can't the provider name be used as the model ID?

OpenClaw resolves the default model as provider/model. The provider is a name you choose in the configuration file; the model is the ID the endpoint actually accepts. If the two are mixed up, the Gateway may start successfully, but model resolution will fail.

Can the configuration file use JSON?

The official example uses JSON5, so comments and trailing commas may work; in practice, follow the configuration file format accepted by your current version. If you hit a parsing error, remove the comments and trailing commas first, and retry with a minimal plain JSON structure.

Why didn't the behavior change after I edited the configuration?

First confirm that the Gateway is reading the configuration file you are editing, then restart the Gateway. Also check whether the current agent is still being overridden by a session or another profile. Do not rely only on whether the dashboard opens; actually confirm which model is currently selected.

Node version is correct, but installation still fails

First check node --version and npm --version, then open a new shell to make sure the same global installation is being run. If you use the official installer, keep the error messages from the installation output and compare them with the Getting Started documentation for that version.

The response is almost empty, and finish_reason is length. What should I do?

This model has thinking enabled by default. If max_tokens is too small, reasoning tokens may use up the budget first, resulting in finish_reason=length and almost no output. Increase max_tokens to fix it; in testing, normal output only appeared after raising it from 16 to 400.

5. Connecting to BazaarLink

Set the provider's baseUrl to https://api.bazaarlink.ai/v1, use <BAZAARLINK_API_KEY> as the apiKey, and fill models[].id with the actual ID from the public model list (this article uses gemini-3.8-flash). The minimal shapes for plain text, tool calls (finish_reason=tool_calls), a 5-chunk SSE stream, and image input (the model read the image and answered with its color) were verified on 2026-09-21. The full OpenClaw session, channel and skill workflow, and Anthropic-format tool and streaming interoperability still cannot be claimed. For more endpoint settings, see the model list and the SDK documentation.

TWD billing · Taiwan invoices · leading AI models · OpenAI-compatible API