XuanShu API

OpenClaw setup guide

Connect OpenClaw to XuanShu API through the Anthropic (Claude) or OpenAI (Codex) channel, with a one-line script, manual install, configuration, a smoke test, rollback, and troubleshooting.

1. Prepare an API key

If you do not have an account yet, register at /register.
Create a key used only by OpenClaw at /keys, setting quota, expiration, and access restrictions as needed.
Store the full key securely right away; the console may show only a redacted value later. Never put it in a repository, screenshot, or chat log.

2. One-line install (recommended)

Running this prompts you to pick a channel and paste your API key; the script writes ~/.openclaw/config.yml. It needs sudo, and it only writes configuration — it does not install OpenClaw itself. Source is at /install/openclaw.sh.

curl -fsSL https://www.xuanshuapi.com/install/openclaw.sh | sudo bash

Install OpenClaw (the one-line script does not install it)The script only writes configuration; do this first before running it

3. Install OpenClaw

Install with npm:

npm install -g openclaw
openclaw --version

The npm package name is openclaw; @openclaw/cli does not exist.
A printed version means the install succeeded.

4. Pick a channel and write the configuration

Models change over time, so check /available-channels for what is currently available. This overwrites any existing configuration, so back it up first.

export ANTHROPIC_API_KEY="<YOUR_API_KEY>"
openclaw onboard --auth-choice custom-api-key \
  --custom-base-url https://www.xuanshuapi.com \
  --custom-api-key-env ANTHROPIC_API_KEY \
  --custom-compatibility anthropic \
  --custom-model claude-opus-4-6

export OPENAI_API_KEY="<YOUR_API_KEY>"
openclaw onboard --auth-choice custom-api-key \
  --custom-base-url https://www.xuanshuapi.com/v1 \
  --custom-api-key-env OPENAI_API_KEY \
  --custom-compatibility openai \
  --custom-model gpt-5.6-sol

5. Run the minimal smoke test

From your project directory, run the command below to start OpenClaw and ask it anything to confirm you get a reply.

openclaw

6. Success criteria

OpenClaw starts normally and returns a model reply; /usage shows a successful request for the selected model; and no 404, 401/403, or 429 appears. Start real project work only after all three checks pass.

7. Roll back the configuration

Back up the configuration file and clear the related environment variables in the current terminal, then start a new login shell.

mv ~/.openclaw/config.yml ~/.openclaw/config.yml.xuanshu-backup
unset ANTHROPIC_API_KEY ANTHROPIC_BASE_URL \
  OPENAI_API_KEY OPENAI_BASE_URL
exec "$SHELL" -l

8. Troubleshooting

Record the status code, request time, model ID, and the request entry in /usage first. Redact the full key before sharing logs.

Symptom	Check	Resolution
404	The Anthropic channel --custom-base-url must be exactly https://www.xuanshuapi.com (no /v1); the Codex channel must include /v1.	Fix --custom-base-url for the channel you are using, rerun onboard, and retry.
401 / 403	Confirm the key in the environment variable is the full, untruncated value and that it has not expired or been revoked.	Copy or create a new key at /keys and export the environment variable again.
Model unavailable	Use the same key to check the exact model ID and current visibility at /available-channels.	Rerun onboard with an updated --custom-model; if a model is temporarily unavailable, switch to an available model on the same protocol.
429	Check balance, key limits, and concurrent requests at /usage.	Reduce concurrency and wait for the limit window to recover; use bounded backoff only for 429.
Configuration not applied	Confirm the write landed in ~/.openclaw/config.yml and that OpenClaw was restarted.	Restart OpenClaw; already-open sessions do not reload automatically after the script writes the file.
Command not found	openclaw is not installed, or the npm global directory is not on PATH.	Run npm install -g openclaw first, then reopen the terminal.