Use AI Hub with OpenClaw

1. Prepare your workspace

Create a workspace inference key in API keys in this AI Hub environment. Give the agent its own key and choose a spend cap. Use the API base below with a key from the same environment; a console login, OpenRouter key or vendor key cannot replace it.

2. Choose your models

Find a model ID

Every AI Hub model has an author/slug ID, such as z-ai/glm-5.3-flash, in the same format OpenRouter uses. Copy IDs from AI Hub's catalogue: an ID copied from OpenRouter may not exist here or may name a different version.

1. Sign in and open Models.
2. Pick the Text tab, then narrow the list: in Capabilities choose Tools, since an agent needs tool calls, and in Context choose a large size, so a long session fits.
3. Select the copy button next to the model's ID. OpenClaw uses it with a tokenhub/ prefix, for example tokenhub/z-ai/glm-5.3-flash.

The same page shows each model's price, context length and inputs. Prices change; check them there rather than in this guide.

Suggested models

These models call tools and hold at least 1 million tokens of context. Start with a flash model and move up when a task needs it.

3. Install and configure OpenClaw

Follow OpenClaw's installation and onboarding guide, including its current Node.js requirement. Supply TOKENHUB_API_KEY securely to the process running the OpenClaw gateway; a terminal variable may not reach a background service. Merge this into ~/.openclaw/openclaw.json, preserving existing settings:

{
  "models": {
    "mode": "merge",
    "providers": {
      "tokenhub": {
        "baseUrl": "https://tokenhub-api.belive.sg/api/v1",
        "apiKey": "${TOKENHUB_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "z-ai/glm-5.3-flash", "name": "GLM-5.3 Flash", "input": ["text", "image"], "contextWindow": 1000000, "maxTokens": 8192 },
          { "id": "deepseek/deepseek-v4.1-flash-1017", "name": "DeepSeek V4.1 Flash", "input": ["text", "image"], "contextWindow": 1024000, "maxTokens": 8192 }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "tokenhub/z-ai/glm-5.3-flash",
        "fallbacks": ["tokenhub/deepseek/deepseek-v4.1-flash-1017"]
      },
      "models": {
        "tokenhub/z-ai/glm-5.3-flash": { "alias": "glm" },
        "tokenhub/deepseek/deepseek-v4.1-flash-1017": { "alias": "deepseek" }
      }
    }
  }
}

• models.providers.tokenhub.models lists the AI Hub models OpenClaw may use. Add an entry for each model you want; id is the catalogue ID without the tokenhub/ prefix.
• primary is the model a new session uses. fallbacks are tried in order when the primary fails, for example on a rate limit, a timeout, an authentication error or a model AI Hub does not serve.
• alias gives each model a short name for switching in chat.
• contextWindow and maxTokens tell OpenClaw how much the model holds and how much it may write per reply. Set contextWindow from the Models page: without it OpenClaw assumes 200,000 tokens and compacts long sessions early. The 8192-token output is a chosen cap, not the model's maximum.

Keep the environment reference literal; do not paste the key into this file.

4. Check selection and run

For an installed gateway service, restart it and open the chat dashboard:

openclaw gateway restart
openclaw dashboard

Check that OpenClaw sees both models and which one is the default:

openclaw models list

tokenhub/z-ai/glm-5.3-flash                 text+image 1000k  Auth yes  default,configured
tokenhub/deepseek/deepseek-v4.1-flash-1017  text+image 1024k  Auth yes  fallback#1,configured

To run one task without the chat dashboard, use openclaw agent --local. The agent reads and writes files in its workspace, ~/.openclaw/workspace by default:

openclaw agent --local --agent main -m "Read notes.txt and run the tests"

Then check Activity for the model, usage and cost of each request.

Switch models

In a chat session:

A model you choose by name with /model or --model does not fall back: if it fails, the request fails. Fallbacks apply when the session uses the configured default.

5. Tips

• Start cheap, then move up. A flash model handles most file editing, search and shell work. Switch the session to a larger model with /model for one hard task, rather than changing the default.
• Use a fallback from a different developer. A GLM primary with a DeepSeek fallback keeps working when one model is rate-limited or busy.
• Give each agent its own key and spend cap. Each key's usage shows separately in Activity, and a cap stops a runaway loop.
• Set contextWindow for every model. OpenClaw compacts the conversation from this number; too low wastes context, too high causes context errors.
• Long sessions cost more per turn. Each turn resends the conversation, so start a new session for an unrelated task.
• Switch early, not late. Some model routes cache a repeated prompt prefix. After a /model switch or a fallback the new model has no cache, so that turn pays full input price for the whole conversation. See Prompt caching.
• Check the allowlist. If agents.defaults.modelPolicy.allow lists models, add tokenhub/*; otherwise OpenClaw refuses /model and --model choices of AI Hub models.
• Check older overrides. Per-agent model settings and ~/.openclaw/agents/<agentId>/agent/models.json can point at another provider and take precedence.
• Restart after changing ~/.openclaw/.env. The gateway reads that file when it starts.

6. Add media features

Each feature below has its own setting in ~/.openclaw/openclaw.json. Merge the blocks you need into the configuration from step 3, keep the key as the ${TOKENHUB_API_KEY} reference, and choose the model for each feature on the Models page, filtered by what it accepts and produces. The commands use openclaw infer, which runs one request without a chat session.

Image understanding

List image in a model's input, as the step 3 configuration does for both models. OpenClaw only attaches images to a model that declares it, and sends them as image_url parts:

openclaw infer image describe --file photo.png --model tokenhub/z-ai/glm-5.3-flash --prompt "What text does this image show?"

If your default model cannot read images, add one that can to the tokenhub model list and set agents.defaults.imageModel to { "primary": "tokenhub/qwen/qwen3.8-flash" }. OpenClaw uses it when the primary model cannot read images.

Video understanding

Add a model that accepts video, and list video in its input:

{ "id": "qwen/qwen3.8-flash", "name": "Qwen3.8 Flash", "input": ["text", "image", "video"], "contextWindow": 1000000, "maxTokens": 8192 }

Give it an alias such as qwen in agents.defaults.models, and switch to it with /model qwen before sending a video. OpenClaw hands a video attached in a chat session to the model as a video_url part with inline base64 data, the form AI Hub accepts. We checked this against AI Hub's request shape and OpenClaw's source; it was not run end to end. Use a model that accepts video input, and keep each file under the request body limit in Video understanding.

Image generation

OpenClaw generates images only through its built-in provider IDs. Point the litellm provider at AI Hub; it calls POST /images/generations:

{
  "models": {
    "providers": {
      "litellm": {
        "baseUrl": "https://tokenhub-api.belive.sg/api/v1",
        "apiKey": "${TOKENHUB_API_KEY}",
        "api": "openai-completions",
        "models": [{ "id": "qwen/qwen-image-2.1-turbo", "name": "Qwen Image 2.1 Turbo", "input": ["text"], "contextWindow": 8192, "maxTokens": 1024 }]
      }
    }
  },
  "agents": {
    "defaults": {
      "mediaModels": { "image": { "primary": "litellm/qwen/qwen-image-2.1-turbo" } }
    }
  }
}

openclaw infer image generate --prompt "A red apple on a white table" --size 1024x1024 --output apple.png

OpenClaw always sends a size (1024x1024 unless you pass one). Use a size the model lists in Image generation; another size is refused. Reference images and edits do not work: OpenClaw sends them to an edits endpoint that AI Hub does not serve.

Video generation

Point OpenClaw's openrouter provider at AI Hub. Its video flow matches AI Hub's job API: it submits to POST /videos, polls the job and downloads the result.

{
  "models": {
    "providers": {
      "openrouter": { "baseUrl": "https://tokenhub-api.belive.sg/api/v1", "apiKey": "${TOKENHUB_API_KEY}", "models": [] }
    }
  },
  "agents": {
    "defaults": {
      "mediaModels": { "video": { "primary": "openrouter/alibaba/wan3.0-video" } }
    }
  }
}

openclaw infer video generate --model openrouter/alibaba/wan3.0-video --prompt "A red balloon floating upward" --resolution 480p --duration 3 --output balloon.mp4

A clip takes minutes. OpenClaw does not send an idempotency key, so a retried submit can start a second job; check Activity before retrying. See Video generation for each model's durations and prices.

Text to speech

Set the openai speech provider's base URL to AI Hub. AI Hub's named voices return WAV only, so set responseFormat to wav:

{
  "tts": {
    "provider": "openai",
    "providers": {
      "openai": {
        "baseUrl": "https://tokenhub-api.belive.sg/api/v1",
        "apiKey": "${TOKENHUB_API_KEY}",
        "model": "qwen/qwen-audio-3.0-tts-flash",
        "voice": "loongjohn",
        "responseFormat": "wav"
      }
    }
  }
}

openclaw infer tts convert --local --text "Hello from AI Hub." --provider openai --output hello.wav

Leave speed unset; it is not part of AI Hub's speech request. Each request takes up to 600 characters. Voices for each model are in Audio.

Speech to text does not work from OpenClaw: it uploads the audio file in the transcription request, while AI Hub takes a file uploaded beforehand.

Troubleshooting

• Authentication failure: check the key is active in the correct workspace and environment, and available to the process running the client. Never print the key to diagnose it.
• Model missing or rejected: copy the exact catalogue ID from Models, add it to the tokenhub model list, check key model restrictions and the modelPolicy.allow list. openclaw models list shows what OpenClaw resolved.
• 404 or transport error: use the API base shown here, including its version prefix, without appending /chat/completions. Select Chat Completions transport.
• Tool or context errors: check supported_parameters and context_length in the catalogue; reduce the session context or output cap. See Errors for gateway responses.
• Unexpected service or missing Activity: review imageModel, mediaModels, fallbacks and local overrides. OpenRouter presets, aliases and plugins are not interchangeable with AI Hub.
• A task stalls on a shell command: the agent's exec approval policy may be waiting for someone to approve the command, possibly in a chat channel. AI Hub is not involved while a command waits.
• OpenClaw shows a cost of 0: it prices runs from the provider's model entries, which this example leaves out. Activity shows the cost AI Hub recorded.

Configuration reference

See OpenClaw's custom-provider reference and environment substitution examples for client settings.