Installing OpenClaw and Configuring OmniProxy

OpenClaw is an AI assistant installed on your own computer. You can talk to it directly through Telegram, Discord, WhatsApp, or Feishu without keeping another chat window open. Conversations and records remain on this computer, and it can continue carrying out subsequent steps locally.

Before You Start

OpenClaw requires Node 24.16 or later. You can also use Node 26.1 or later, with Node 26 recommended. Node provides the runtime environment required by OpenClaw.

It can be installed on macOS, Linux, and Windows. If the computer does not have a suitable version of Node, the installation script will prepare one automatically: Node 26 on macOS and Node 24 LTS on Linux. pnpm is required only when building OpenClaw from source.

If an older version of Node is already installed, you do not need to uninstall it first. During testing on 2026-10-09, the system Node version on this computer was 24.2.0, below the required 24.16, and the non-interactive installation script prepared Node 24.21.0 automatically.

Want a window

Desktop companion

• Use the Hub installer on Windows
• Use the GitHub DMG on macOS
• The local Gateway can be installed during initial setup

Officially recommended

Installation script

• macOS Linux WSL2
• Use PowerShell on Windows
• You can add --no-onboard

Node already installed

Package manager

• npm pnpm or bun
• Then run onboard
• See the installation page for the Node version

Install and Launch for the First Time

You can install the desktop companion with a graphical window, or install directly through the terminal. Gateway is the local service responsible for receiving messages, calling models, and returning the results. You can set it up when opening the desktop companion for the first time.

If You Want a Window

• Windows: Download and run OpenClawCompanion-Setup-x64.exe or OpenClawCompanion-Setup-arm64.exe. The installer is signed and includes settings, tray status, chat, and node modes.
• macOS: Download the OpenClaw .dmg from OpenClaw’s GitHub releases. Prefer the dmg, though you can also use the .zip. Open OpenClaw.app after installation. If this version does not include a macOS file, follow the macOS app page.

When opening it for the first time, you can let OpenClaw prepare Gateway on this computer or connect to an existing remote Gateway.

Install Through the Terminal

For macOS, Linux, and WSL2, use:

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

For Windows PowerShell, use:

iwr -useb https://openclaw.ai/install.ps1 | iex

The script detects the current system, installs Node when needed, installs OpenClaw, and then starts the initial onboarding process. The onboarding flow guides you through the first-time setup.

If you do not want to start onboarding yet, use the following instead on macOS, Linux, and WSL2:

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

On Windows, use the official -NoOnboard option:

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

If you already manage Node yourself, you can also use npm, pnpm, or bun. With npm 12 or npm 11.16 and later, run:

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

For npm 11.15 and earlier, remove --allow-scripts=openclaw. When using pnpm, add --allow-build=openclaw. Refer to the installation page for the exact differences.

After installation, run these three commands in order:

openclaw --version
openclaw doctor
openclaw gateway status

openclaw --version displays the version, openclaw doctor checks for common environment issues, and openclaw gateway status shows whether Gateway is running. The basic installation is complete only when all three commands produce normal output.

If the terminal reports that it cannot find openclaw, the npm global bin directory is usually missing from PATH. PATH is the list of locations where the terminal looks for programs. Compare the output of node -v, npm prefix -g, and echo "$PATH", add the corresponding bin directory to PATH, and then reopen the terminal.

If ~/.openclaw already contains a configuration currently in use, the default installation script will use that directory. To install a separate copy without changing the existing configuration, run the non-interactive script and specify a new directory:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix "$HOME/openclaw-omniproxy" --no-onboard

--no-onboard is the default behavior of this script. On 2026-10-09, this command installed OpenClaw 2026.9.9. After installation, run the openclaw executable from the directory’s bin folder.

Get Connection Values from OmniProxy

First confirm that OmniProxy is running, then open its model list and prepare the following three values:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: copy the full value from the current OmniProxy model list

baseUrl is the address to which OpenClaw sends model requests, and it must end with /v1. When connecting to OmniProxy, use openai-completions for api. Change it to openai-responses only if the model actually works through /v1/responses.

The Model ID is the model’s complete identifier in the list. Copy it exactly as shown, including any slashes. The following two names are only references from provider documentation as of 2026-10-09; do not use them if they do not appear in the list: claude-sonnet-5-5, gpt-6-luna.

Even if the gateway does not validate the key, apiKey must still contain a value. You can use a placeholder string that is used only on this computer. Do not commit a real key to a repository.

Enter the Tool Configuration

A Provider can be understood as a set of connection settings that OpenClaw uses to locate a model service. Here, the Provider is named omniproxy.

Run the following command in the terminal, replacing the address, key, and two model IDs with your own values:

openclaw config set models.providers.omniproxy '{"baseUrl":"https://your-omniproxy-origin.example/v1","apiKey":"<YOUR_OMNIPROXY_API_KEY>","api":"openai-completions","models":[{"id":"claude-sonnet-5-5","name":"Claude Sonnet 5.5"},{"id":"gpt-6-luna","name":"GPT-6 Luna"}]}' --strict-json --merge

This command writes the Provider and model list to the configuration. You do not need to restart Gateway after the command succeeds.

Next, specify the default model. The model reference consists of omniproxy/ followed by the model ID. Preserve every slash already present in the ID. If the ID in the model list is longer than the short name below, use the complete value from the list:

openclaw config set agents.defaults.model.primary '"omniproxy/claude-sonnet-5-5"' --strict-json

reasoning, input, cost, contextWindow, and maxTokens can all be omitted. When they are not provided, text models are handled using the defaults.

You can also write the same settings directly into the configuration file. In the main configuration, the Provider is located under models.providers. Each agent can also have its own models.json; an agent is an assistant instance that actually receives tasks and calls models. The file is located at agent/models.json within the corresponding agent directory under ~/.openclaw/agents/.

If this models.json contains a non-empty baseUrl, it overrides the address in the main configuration.

Check installation

Three commands

• openclaw --version
• openclaw doctor
• gateway status

Configuration

models.providers

• baseUrl ends with /v1
• Set api to completions
• Specify at least the model id

Select

provider/model

• Use this reference for primary
• Prefer an environment variable for the key
• Use the gateway list as the source of truth

Verify a Real Task

Enter a regular project directory and send a very short message. Replace the model reference in the command with your complete Model ID:

openclaw agent --local --model omniproxy/claude-sonnet-5-5 --timeout 300 --message "Reply with one word."

--local runs this agent task locally, --model specifies the model to use for this run, and --timeout 300 sets the maximum wait time to 300 seconds.

An actual model response must appear in the terminal. On 2026-10-09, OpenClaw 2026.9.9 received a response using this command. The first call may take one or two minutes.

If the original error Request timed out before a response was generated appears, increase --timeout and send the request again. This usually means the wait time was insufficient and does not necessarily indicate that the address is incorrect.

After the short response succeeds, ask it to read a local file that you specify. Then open OmniProxy’s request records and confirm the source and model ID shown in the record. Output from only the version command or doctor does not mean that the model connection has been fully configured.

Installation

The command responds

• The version number is displayed
• doctor reports no blockers
• Gateway status is readable

Task

It completed a small task

• For example, read a local file
• The response is not an error
• The model reference is correct

Logs

Visible in the gateway

• Source is OpenClaw
• Model ID matches
• The key was not added to the repository

Common Errors

• Cannot find openclaw: Add the npm global bin directory to PATH, then reopen the terminal. If you installed to a specified directory, run the executable from that directory’s bin folder.
• node -v is below 24.16: You do not need to uninstall the old version first. Check the Node version prepared by the installation script, or use 24.16+ or 26.1+ as described on the installation page. Node 26 is recommended.
• The model does not appear: The model must be included in the models array under models.providers and must at least have the same id. Setting only agents.defaults.models does not register a new model by itself.
• A 400 response mentions the developer role: When the address host is not api.openai.com, keep the default and do not set supportsDeveloperRole to true. Even if it is set to true, it will still be overridden.
• It times out quickly: Increase --timeout to more than 300 seconds before changing the address.
• Tool calls fail after selecting gpt-6-luna: It supports Chat Completions; function calling in Chat Completions is supported only when reasoning_effort is none. If the ID in the list differs from this one, use the ID shown in the list.
• The address cannot be reached: Confirm that OmniProxy is running, that baseUrl ends with /v1, and that the address written to the configuration is accessible. Other private-network addresses must be allowed separately.
• Requests still go to another address after configuration: Check whether that agent’s models.json contains a different baseUrl.

Official References

For installation steps, see OpenClaw install. For custom Provider configuration, see Custom providers and configuration fields. For the model IDs used in the examples, compare against Claude model overview and GPT-6 Luna.

Replace every placeholder with values from your own OmniProxy configuration. Never publish a real key.

A saved result or HTTP 200 alone does not prove full Agent compatibility. Check the source and model in OmniProxy's call record.

Official sources · OpenClaw ↗