Check each configured fallback model before you need it. This small, local CLI reads OpenClaw's global fallback list and can make one opt-in request to each model on its own.
It is an independent community utility and is not affiliated with or endorsed by OpenClaw or its maintainers.
Provider authentication can work while one configured model ID is unavailable. OpenClaw users have also reported fallback-chain failures during provider errors. This tool answers a narrower question: does each model in my configured global fallback list respond to one direct OpenClaw run right now?
It is not a fallback router, monitor, or failover simulation.
- OpenClaw #6599: a request for checking configured fallback models before an outage.
- OpenClaw #63145: a request to check each configured model rather than only provider authentication.
- OpenClaw #141115: a report of configured fallbacks not being used after a provider error.
These are issue reports, not a measurement of how common the failure is or proof that this tool fixes live failover.
Requirements: Python 3.9+ and an installed, configured OpenClaw CLI.
Install the ready-to-use wheel from the v0.1.0 release, or install from a source checkout:
python -m pip install https://github.com/LydiaTools/openclaw-fallback-check/releases/download/v0.1.0/openclaw_fallback_check-0.1.0-py3-none-any.whl
# or, from the repository root
python -m pip install .
openclaw-fallback-checkThe release includes a SHA-256 file for the wheel.
The default command prints the primary model and fallback candidates. It reads agents.defaults.model using OpenClaw's config command and sends no model request.
To run one live probe per configured fallback:
openclaw-fallback-check --probeThe CLI asks before sending requests in an interactive terminal. In scripts, pass --yes explicitly:
openclaw-fallback-check --probe --yes --json-out fallback-report.jsonEach probe makes one short generation request through openclaw agent exec, selects that candidate as primary, and clears the fallback list for that individual run. This prevents another fallback from hiding a model that cannot respond. No automatic retry is performed. Provider quota or charges may apply.
--json-out creates a new report and refuses to overwrite an existing file. Reports contain model IDs, pass/fail/timeout status, elapsed time, and process exit codes. Provider response text and raw subprocess output are not saved or printed.
The repository includes a fake OpenClaw executable; it uses no network or credentials:
python -m pip install .
openclaw-fallback-check --openclaw ./examples/mock-openclaw
openclaw-fallback-check --openclaw ./examples/mock-openclaw --probe --yes
python -m unittest discover -s tests -vThe fixture intentionally returns one pass and one failure so the report path can be inspected.
- Pass: the selected model completed one direct OpenClaw generation during this check.
- Fail: that invocation exited unsuccessfully.
- Timeout: the invocation exceeded its configured time limit.
This check does not inject a real provider outage or HTTP 429, verify that OpenClaw automatically switches models in a live conversation, test tools or semantic quality, or guarantee that a future request will succeed. It currently reads only agents.defaults.model; agent-specific model overrides are outside scope. A successful individual probe is evidence of a response at that moment, not proof that the full failover path works.
The implementation follows the documented config get and agent exec interfaces.
- Default is a plan-only read.
- Live calls require
--probeand an interactive confirmation, or explicit--yesin non-interactive use. - One request per fallback; no retry loop.
- The tool does not edit OpenClaw's configuration.
- Raw provider output is discarded; only a small redacted status report is available.
- No third-party Python runtime dependencies.
MIT. See LICENSE.
See README.zh-CN.md.