OpenClaw Promos CLI: List and Claim Promotional Models

openclaw promos

Browse and activate promotional model offers shared on ClawHub. When you claim a promotion, it sets up the provider (including authentication and any required plugin), then adds the promotion's models to your configuration. This happens without rerunning the onboarding process, and your default model stays unchanged unless you explicitly allow it.

See also:

• Configuring the default model and fallbacks: Models
• Provider authentication setup: Getting started

Commands

openclaw promos list
openclaw promos claim <slug>
openclaw promos claim <slug> --api-key <key> --set-default

openclaw promos list

Shows all currently active promotions, including their models, the recommended default, how much time is left, and the exact command to claim them. Use --json to see the unprocessed response data.

openclaw promos claim <slug>

Activates an active promotion:

1. Retrieves the promotion from ClawHub and confirms it falls within the valid time window.
2. Checks the promotion's provider, authentication method, and listed plugin packages against your installed OpenClaw release. Unknown identifiers or package conflicts are rejected. A promotion can never force the CLI to execute anything beyond its existing capabilities.
3. Uses your current provider credentials if they are already stored. If not, it runs the provider's standard authentication process, first showing the promotion's signup link for a free API key. --api-key <key> handles API-key authentication without any interactive prompts, behaving like the openclaw onboard non-interactive flags. To avoid putting the key directly on the command line, set the provider's environment variable instead, for example OPENROUTER_API_KEY. Existing environment credentials are picked up automatically, so no flag is necessary.
4. Adds the promotion's models under their designated aliases. No existing aliases are overwritten.
5. Asks whether to make the promotion's suggested model your new default. Using --set-default bypasses this prompt; otherwise, your default settings remain untouched.

Once the promotion's window expires, the provider stops serving the free models, but your configuration and credentials are preserved. To return to your previous setup, run openclaw models set <model>.

Passive discovery in models list

openclaw models list also reveals promotions without needing to query ClawHub directly:

• Unconfigured models from active offers are grouped under an "Available via promotion" section below the main table, each accompanied by its claim command.
• Models you added through promos claim display a promo badge, which changes to promo ended after the offer's window has ended.
• When a new offer appears for the first time, a one-time notification directs you to openclaw promos list. Offers you have already viewed or claimed are never mentioned again.

This feature reads a locally cached version of ClawHub's promotions feed, which typically refreshes once daily using a conditional request, or sooner if the cached data expires. Refresh failures are ignored silently. A stale refresh waits no more than 2.5 seconds and never prevents the listing from appearing. Output from --json and --plain remains machine-friendly, with no promotion sections or notices. Claiming always validates against the live ClawHub API, so an offer removed early is rejected even if a cached copy still shows it.