OpenClaw with AIXHUB

Use this guide with the canonical, officially maintained OpenClaw project. Unrelated projects can use the same name but different commands and configuration formats; do not mix their instructions or files with this setup.

What you will accomplish

By the end of this guide, you will have:

1. Installed the canonical OpenClaw npm package and confirmed its version.
2. Backed up the existing user configuration before merging an AIXHUB provider.
3. Supplied a dedicated AIXHUB key without displaying it or storing the real value in JSON.
4. Selected aixhub/panel-model-id as the primary model.
5. Completed a tool-free text request and matched it with AIXHUB Usage.
6. Kept a clear path to restore the previous provider and primary model.

System requirements

• macOS or Linux with a supported Node.js release and npm available on PATH.
• On Windows, use WSL and run every install, configuration, and OpenClaw command inside the same WSL distribution. Native Windows support is limited for this guide.
• An AIXHUB account, a dedicated AIXHUB API key, and an OpenAI Responses-compatible model ID copied from Model routes. This guide uses panel-model-id.
• A text editor that preserves valid JSON.

The user configuration is ~/.openclaw/openclaw.json. On Windows, ~ means the Linux home directory inside WSL, not %USERPROFILE%. Back up an existing file before editing it, and preserve unrelated providers, agents, and other settings when merging this guide's values.

Install

Install or update the canonical OpenClaw npm package:

npm install -g openclaw@latest

Open a new terminal in the same operating-system environment and confirm the executable and version:

openclaw --version

Resolve npm permission or PATH errors before editing provider settings. If the installed program does not recognize the canonical OpenClaw commands, remove the unrelated package or executable from PATH before continuing.

AIXHUB configuration

Back up the current configuration

Create the user directory and make a uniquely named timestamped copy before changing an existing configuration:

if ! mkdir -p "$HOME/.openclaw"; then
  printf 'Cannot prepare ~/.openclaw. Stop before editing openclaw.json.\n' >&2
  false
elif [ -f "$HOME/.openclaw/openclaw.json" ]; then
  backup=""
  if backup="$(mktemp "$HOME/.openclaw/openclaw.json.backup.$(date +%Y%m%d%H%M%S).XXXXXX")" && cp "$HOME/.openclaw/openclaw.json" "$backup"; then
    printf 'Backup created: %s\n' "$backup"
  else
    [ -z "$backup" ] || rm -f "$backup"
    printf 'Backup failed. Stop before editing openclaw.json.\n' >&2
    false
  fi
else
  printf 'No existing openclaw.json; no backup was needed.\n'
fi

The same command works in Bash, zsh, and WSL. If an old file exists, continue only after you see Backup created: and record the exact path printed for this operation. If no old file exists, No existing openclaw.json; no backup was needed. is the successful result; after confirming that no external or generated configuration supplies these fields, record all three original states below as absent. If either Cannot prepare ~/.openclaw. Stop before editing openclaw.json. or Backup failed. Stop before editing openclaw.json. appears, stop immediately and do not edit the configuration. The failure branches return a nonzero result without closing an interactive shell, and a failed copy removes any temporary empty or incomplete file. mktemp adds a unique suffix to the timestamp, so repeated runs create new files instead of overwriting the first backup. A backup can contain credentials for other providers, so keep its path and contents private.

Before merging, inspect the current JSON and record these three original states in a private note:

If models.providers.aixhub already exists, decide explicitly whether replacing it is intended. Keep its complete original object in the protected note and timestamped backup; do not assume it was created by this guide or can later be deleted.

Set the key for the current terminal

Use the block for the shell that will start OpenClaw. Each method accepts the key without echoing it and avoids placing the real value in shell history.

Bash and Windows WSL

read -r -s -p "AIXHUB API key: " AIXHUB_KEY
printf '\n'
export AIXHUB_API_KEY="$AIXHUB_KEY"
unset AIXHUB_KEY

zsh

read -r -s "AIXHUB_KEY?AIXHUB API key: "
printf '\n'
export AIXHUB_API_KEY="$AIXHUB_KEY"
unset AIXHUB_KEY

This variable is available only to the current shell and programs started from it. For persistent use, prefer a secret manager that injects AIXHUB_API_KEY. If local policy permits a shell profile, edit a user-only profile directly with a text editor and restrict its permissions; do not use a command that writes the real key into shell history.

Merge the provider configuration

Merge the following objects into ~/.openclaw/openclaw.json. The example is a complete, valid configuration for this provider, but an existing file may contain other settings that must be preserved.

{
  "models": {
    "mode": "merge",
    "providers": {
      "aixhub": {
        "baseUrl": "https://api.aixhub.org/v1",
        "apiKey": "${AIXHUB_API_KEY}",
        "api": "openai-responses",
        "models": [
          {
            "id": "panel-model-id",
            "name": "AIXHUB model"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "aixhub/panel-model-id"
      }
    }
  }
}

Property names are case-sensitive. OpenClaw uses baseUrl, not OpenCode's baseURL or Codex CLI's base_url. Keep apiKey, api, models, and primary exactly as shown. The Base URL must contain exactly one /v1, and api must be openai-responses.

The model ID in the provider's models array and the suffix in aixhub/panel-model-id must be identical. Do not add guessed contextWindow, maxTokens, or capability values; this minimal route does not need them.

Validate the merged file before starting OpenClaw:

node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")); console.log("JSON OK")' "$HOME/.openclaw/openclaw.json"

If the file already defines models, merge mode and providers.aixhub into that object. If it already defines agents, merge only defaults.model.primary after recording the previous primary model. Do not replace unrelated objects.

First run

Run the built-in diagnostic from the same shell where AIXHUB_API_KEY is set:

openclaw doctor

Resolve JSON or provider-loading errors before sending a request. Use openclaw --help to confirm the commands exposed by the installed release; if the expected commands are absent, resolve the package or version mismatch first.

List the available models. Run models set only when the list does not show aixhub/panel-model-id as the selected model, because set writes the model choice to the configuration:

openclaw models list
openclaw models set aixhub/panel-model-id

After confirming the model, run one local agent turn:

openclaw agent --local --session-key aixhub-verification --message "Do not call tools, access files, or run commands. Reply with OK only."

--local avoids requiring a configured Gateway for this first test. --session-key aixhub-verification supplies the agent selector and gives the verification turn a distinct session. This command sends the bounded request directly; do not start the bare openclaw CLI and wait for a manual prompt.

Verification

A successful text response should contain this output:

OK

Then open AIXHUB Usage and find a new OpenAI Responses request for panel-model-id. Confirm that the time matches the test and that the aixhub-verification agent turn used the aixhub provider rather than another merged provider or official account.

Troubleshooting

Configuration is not loaded or JSON is invalid

Confirm that the file is exactly ~/.openclaw/openclaw.json in the environment that runs OpenClaw. Windows users must edit the WSL Linux home file. Re-run the JSON validation and openclaw doctor, then repeat the local agent turn. Preserve the outer models and agents objects when merging instead of duplicating them.

401 or authentication failed

Run the agent turn from the same shell where AIXHUB_API_KEY was entered. Keep the JSON value exactly as ${AIXHUB_API_KEY}; do not replace it with an official OpenAI login, an AIXHUB dashboard password, or a printed key. Re-enter a current dedicated key without echoing it, then repeat the local agent turn.

404 or an endpoint error

Keep baseUrl exactly https://api.aixhub.org/v1 and api exactly openai-responses. A missing /v1, a duplicated /v1/v1, or the wrong capitalization can route the request incorrectly.

model not found

Copy the exact ID again from Model routes. Update both the id in the provider array and the suffix of primary: "aixhub/panel-model-id". The aixhub/ prefix belongs in primary, not in the provider model id.

Text succeeds but a tool fails

A successful text response and matching Usage record show that the provider route works. Diagnose the tool's permission, schema, arguments, and local OpenClaw configuration separately; do not change the Base URL or key to fix a tool-layer failure. Keep tools disabled until the text route remains stable.

Usage has no matching request

Check the model selected for the aixhub-verification session with openclaw models list. Because models.mode is merge, other providers remain available and an agent-level override may still select one. If needed, run openclaw models set aixhub/panel-model-id, knowing that it writes the configuration, then repeat the local tool-free agent turn. For 403, 429, 502, or 503 responses, continue with the error code reference.

Upgrade and restore

Back up the configuration before upgrading, then install the latest package and confirm the version:

npm install -g openclaw@latest
openclaw --version

After an upgrade, run openclaw doctor, confirm the model for the verification session, and repeat the local tool-free agent turn before enabling tools.

If a backup exists, close OpenClaw and restore the entire configuration from the exact timestamped path printed and recorded when this operation began. Do not guess which backup is correct from the newest filename. Replacing the current file with that recorded backup restores all three original states together; validate the restored JSON before continuing.

If no usable backup exists, use the private original-state note. Restore the exact original value of models.mode, the complete original models.providers.aixhub object, and the exact original value of agents.defaults.model.primary wherever the note records a value or object. Delete one of these fields only when its recorded original state is explicitly absent. If an original state is unknown, stop: do not guess, delete a provider, or alter the primary model until a trusted copy of the original configuration is available.

Close the temporary terminal to clear AIXHUB_API_KEY. From a new shell, use openclaw models list to confirm the restored session model, then run a local tool-free agent turn before granting tool access.

Security

• Keep the real key out of openclaw.json. ${AIXHUB_API_KEY} is an environment reference and can remain in the file.
• Create a dedicated AIXHUB key for OpenClaw so it can be rotated or revoked without affecting other clients.
• Never print the environment variable, paste the key into a prompt, commit it, or include it in screenshots and support logs.
• Restrict openclaw.json and every timestamped backup to the current user because other provider entries may contain sensitive values. After the recovery window ends and the restored configuration is verified, clean up backups that are no longer required according to local security policy.
• On Windows, keep the configuration and secret mechanism inside the same WSL distribution that runs OpenClaw.
• Verify the provider with a tool-free request first, then review every tool permission and argument before enabling it.
• Rotate the key immediately if it appears in shell history, a repository, a patch, or a shared log.

Official sources

• OpenClaw model providers

Last verified: 2026-07-14