Component
skill
Problem Statement
The install-openclaw skill can complete config writing and start the OpenClaw Gateway even when the resolved API Key, BaseUrl, and Model ID combination is invalid.
From a user's perspective, the failure is discovered too late. The visible symptom can be a vague Gateway or agent-side error such as gateway disconnected, instead of a clear explanation that the API key is invalid, the endpoint does not match the selected billing plan, or the model is unavailable for that endpoint.
This makes one-shot non-interactive installation unreliable, especially for Coding Plan, Token Plan, and custom compatible endpoints.
Current implementation already supports --base-url and has default endpoints for pay-as-you-go, Coding Plan, and Token Plan, but the skill documentation does not make the custom endpoint path obvious enough. Small agents may still assume the setup is tied to the standard DashScope endpoint.
Proposed Solution
Add a pre-flight validation step to install_openclaw.py before writing config and starting Gateway.
After resolving billing, provider id, BaseUrl, API key, and primary model, the script should make a lightweight API call using the same endpoint configuration that will be written into OpenClaw config.
If validation fails, stop before Gateway startup and print an actionable diagnosis, for example:
- API key rejected or expired.
- BaseUrl does not match the selected billing plan.
- Model ID is not available for the selected plan or endpoint.
- Network or DNS error reaching the endpoint.
- Endpoint returned an unexpected API format.
Suggested flags:
--skip-preflight for offline/debug cases.--preflight-timeout to bound the lightweight check.
Also update SKILL.md to explicitly document:
--base-url is supported.- Coding Plan and Token Plan use dedicated endpoints by default.
- Custom compatible endpoints should be passed with
--base-url.
- Gateway startup should happen only after pre-flight succeeds, unless
--skip-preflight is explicitly passed.
Alternatives Considered
Relying on openclaw gateway health is not enough because it only verifies Gateway health. It does not prove that the configured model endpoint can authenticate and serve the selected model.
Relying on openclaw agent --message "hello" after startup also detects the issue too late and may surface as a vague Gateway or fallback error.
Additional Context
Current code references:
src/os-skills/ai/install-openclaw/scripts/install_openclaw.py already supports --base-url.dependency_precheck() checks local dependencies only.validate_api_key_for_billing() only performs a basic Coding Plan key-shape check.start_gateway() starts/restarts Gateway and waits for openclaw gateway health, but does not validate model authentication or model availability.SKILL.md lists normal parameters but does not clearly document --base-url usage.
Component
skill
Problem Statement
The
install-openclawskill can complete config writing and start the OpenClaw Gateway even when the resolved API Key, BaseUrl, and Model ID combination is invalid.From a user's perspective, the failure is discovered too late. The visible symptom can be a vague Gateway or agent-side error such as
gateway disconnected, instead of a clear explanation that the API key is invalid, the endpoint does not match the selected billing plan, or the model is unavailable for that endpoint.This makes one-shot non-interactive installation unreliable, especially for Coding Plan, Token Plan, and custom compatible endpoints.
Current implementation already supports
--base-urland has default endpoints for pay-as-you-go, Coding Plan, and Token Plan, but the skill documentation does not make the custom endpoint path obvious enough. Small agents may still assume the setup is tied to the standard DashScope endpoint.Proposed Solution
Add a pre-flight validation step to
install_openclaw.pybefore writing config and starting Gateway.After resolving billing, provider id, BaseUrl, API key, and primary model, the script should make a lightweight API call using the same endpoint configuration that will be written into OpenClaw config.
If validation fails, stop before Gateway startup and print an actionable diagnosis, for example:
Suggested flags:
--skip-preflightfor offline/debug cases.--preflight-timeoutto bound the lightweight check.Also update
SKILL.mdto explicitly document:--base-urlis supported.--base-url.--skip-preflightis explicitly passed.Alternatives Considered
Relying on
openclaw gateway healthis not enough because it only verifies Gateway health. It does not prove that the configured model endpoint can authenticate and serve the selected model.Relying on
openclaw agent --message "hello"after startup also detects the issue too late and may surface as a vague Gateway or fallback error.Additional Context
Current code references:
src/os-skills/ai/install-openclaw/scripts/install_openclaw.pyalready supports--base-url.dependency_precheck()checks local dependencies only.validate_api_key_for_billing()only performs a basic Coding Plan key-shape check.start_gateway()starts/restarts Gateway and waits foropenclaw gateway health, but does not validate model authentication or model availability.SKILL.mdlists normal parameters but does not clearly document--base-urlusage.