OpenClaw Installation and Custom API Setup Guide — macOS

Tested version: OpenClaw 2026.6.8.

Goal of this guide: install OpenClaw from scratch on macOS and connect it to "your own OpenAI / Anthropic compatible API endpoint".

Follow the steps below in order. If you run into trouble, see "Quick Troubleshooting" at the end.

OpenClaw (nicknamed "the lobster" 🦞) is an open-source AI agent that runs on your own computer. It does not include a model itself; you provide your own API key, and model fees are paid directly to the provider.

Important Security Notes (please read first)

• OpenClaw has broad system permissions: it can read files, run commands, send messages, and browse the web. It is not recommended to install it on your main machine that syncs a lot of sensitive data (iCloud, passwords, photos); if possible, use a dedicated machine or a clean user account.
• Never expose the Control UI to the public network. Keep it on localhost, or behind a Tailscale / SSH tunnel.
• Always install the latest version. OpenClaw has had serious security vulnerabilities (such as CVE-2026-25253); older versions are exposed to known attacks.
• Token usage can be high during initial setup. Remember to set a usage limit in your provider's console to avoid unexpected costs.

Prerequisite: Node.js

You need Node.js 24 (recommended) or 22 LTS (minimum 22.19+). Check the version:

node --version

If it is missing or too old, install it with Homebrew (Apple Silicon will automatically get the correct ARM64 build):

brew install node

Official one-line script (auto-detects the OS, installs Node if needed, then installs and launches onboarding):

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

Or, if you already have Node, use npm directly:

npm i -g openclaw

If you see this during installation:

npm error code EACCES
npm error path /usr/local/lib/node_modules/openclaw
npm error Error: EACCES: permission denied, mkdir ...

It means the npm global directory is owned by root and a normal user cannot write to it. Recommended fix (move the global directory to your home folder, so future updates do not need sudo):

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g openclaw@latest

Note: if you later get command not found: openclaw in a new terminal window, the PATH has probably not taken effect yet. Reopen the window, or run source ~/.zshrc again.

Verify the installation:

openclaw --version

Run:

openclaw onboard

It will ask the following in order; just choose as below:

• Security disclaimer → Yes: confirms you understand this is a personal default and that shared use needs locking down. For your own use, choose Yes.
• Setup mode → QuickStart: the recommended quick local setup; details can be changed later.
• Model / auth provider → Skip for now: since you are connecting a custom API, the wizard has no field for baseUrl, so skip it and edit the config file later.
• Messaging apps (Telegram / WhatsApp…) → skip all: it is simplest to first confirm chatting works via the web dashboard; connect them later if you want.
• Generate gateway token? → Yes: adds a lock to the dashboard; recommended even for local use.
• Tighten permissions to 600? → Yes: the config file contains your API key, so tighten it so only you can read/write.
• Create session store dir? → Yes: the directory that stores conversation memory; required for normal operation.
• Disable 44 unavailable skills? → No: those skills simply have not had their dependencies installed yet. Keeping them does not affect operation, and they become usable once installed.

After it finishes, set the Gateway mode (for your own local use):

openclaw config set gateway.mode local

Because you chose Skip during onboarding, the config file may not exist yet. Create and edit it manually:

mkdir -p ~/.openclaw
touch ~/.openclaw/openclaw.json
open -e ~/.openclaw/openclaw.json

Paste in the following (replace "your-key" with your real API key; change baseUrl / model id to your provider's values):

{
  models: {
    mode: "merge",
    providers: {
      myai168: {
        baseUrl: "https://www.myai168.com/en/api/openai/v1",
        apiKey: "your-key",
        api: "openai-completions",
        models: [
          {
            id: "gpt-5.5",
            name: "GPT-5.5",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 32000
          }
        ]
      },
      myai168_claude: {
        baseUrl: "https://www.myai168.com/en/api/anthropic/v1",
        apiKey: "your-key",
        api: "anthropic-messages",
        models: [
          {
            id: "claude-opus-4-8",
            name: "Claude Opus 4.8",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 32000
          }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: { primary: "myai168_claude/claude-opus-4-8" },
      models: {
        "myai168_claude/claude-opus-4-8": {},
        "myai168/gpt-5.5": {}
      }
    }
  }
}

Mapping from opencode config to OpenClaw

• opencode's baseURL → OpenClaw's baseUrl (lowercase u; the casing differs).
• opencode's npm:@ai-sdk/openai → OpenClaw's api:"openai-completions".
• opencode's npm:@ai-sdk/anthropic → OpenClaw's api:"anthropic-messages".
• opencode only needs the model name → OpenClaw needs two steps: define it under providers and also add it to the allowlist under agents.defaults.models, otherwise you get "model not allowed".

Allowed values for the api field: openai-completions / openai-responses / anthropic-messages / google-generative-ai.

primary is the default main model; to default to gpt-5.5, change it to "myai168/gpt-5.5". The baseUrl of an OpenAI-compatible endpoint usually has to end with /v1.

Editor pitfall

When using TextEdit, it automatically converts straight quotes into curly quotes, which breaks the JSON. To prevent this: uncheck "Edit → Substitutions → Smart Quotes" in the menu bar; or use a terminal editor instead, for example:

nano ~/.openclaw/openclaw.json

(In nano, save with Ctrl + O then Enter, and exit with Ctrl + X.)

openclaw doctor          # Check the config for problems
openclaw models list     # Confirm the models are loaded

models list should show your models, with the Auth column set to yes and the default model carrying the default,configured tags. For example:

Model                              Input   Ctx    Local  Auth  Tags
myai168_claude/claude-opus-4-8     text    195k   no     yes   default,configured
myai168/gpt-5.5                    text    195k   no     yes   configured

(If a claude-cli/... entry also appears, that was auto-detected from a local Claude CLI; you can ignore it.)

Open the dashboard to try chatting:

openclaw dashboard       # Opens http://127.0.0.1:18789/ in the browser

Or test quickly right in the terminal:

openclaw chat "Hello, just testing"

If it replies normally, the whole setup is done and connected to your custom API.

• npm ... EACCES → global directory permission issue; see "2. Fix the npm Permission Error" and move the prefix to ~/.npm-global.
• command not found: openclaw → PATH has not taken effect; run source ~/.zshrc or reopen the terminal.
• open -e ...openclaw.json says the file does not exist → it has not been created yet; run touch ~/.openclaw/openclaw.json first.
• doctor reports a JSON syntax error → usually the editor changed straight quotes into curly quotes; turn off smart quotes and paste again.
• Replies report a model-related error → the model id or endpoint path does not match the provider's actual values; fix it against the provider's documentation.
• Want to change the main model → edit agents.defaults.model.primary in the config file.

Update (to get new features and security patches):

openclaw update
or
npm update -g openclaw

Run a security audit regularly:

openclaw security audit --deep
openclaw security audit --fix

Config file location: ~/.openclaw/openclaw.json (the same directory also has state/, logs/, etc.).

Official docs: https://docs.openclaw.ai