Onboard a provider without leaking its credential

Verifiedon 2026-07-302026.7.1-2

A provider credential is an operating boundary

A provider key is not “just configuration”. It is authority to spend money, access a model account, and potentially expose the prompts sent through that account. This lesson deliberately uses one provider and one revocable test credential. It does not ask you to import a personal account, reuse a production key, or prove that SecretRefs isolate a process. The OpenClaw secrets guide explicitly says SecretRefs reduce plaintext persistence but are not process isolation; the agent can still access readable files and the resolved value exists at the final adapter boundary.

The reviewed source is OpenClaw 2026.7.1-2, revision 1237c0cf8157a6ad4a900d6b165ea8c830449e78. Read the onboarding CLI reference for the provider flow at that revision. The command names, provider choices, and supported SecretRef surfaces can change; never infer current behavior from an old screenshot.

Before onboarding

Create the credential at the provider, not in a note. Set a fixed spend limit or trial budget, restrict project or organisation scope where available, and make sure you know where the provider revocation control lives. If the provider offers separate keys for development, use that surface. A “temporary” credential with unlimited spend is still a production risk.

Check the terminal, clipboard, shell history, screen-sharing policy, and evidence destination. Disable shell history for the one entry only when your platform’s documented method is reliable; do not pretend that a history toggle protects a value already pasted into a terminal recorder. Prefer a masked prompt or a provider SecretRef environment/file mechanism supported by the reviewed onboarding flow. Never test whether a key “looks right” with printf, an HTTP request, or a diagnostic command that may log its argument.

Lab: guided onboarding with a redacted ledger

Run the documented interactive command as the same test user from the installation lesson:

openclaw onboard

Select one provider and one model. If the flow offers a SecretRef-backed choice, use it only after checking the SecretRef contract for the exact credential surface. The source distinguishes environment references, file providers, and exec providers; it also warns that a file:... string in a literal env block is not resolved as a SecretRef. Do not invent a configuration shape from memory.

When onboarding performs a live inference check, record the result as a fact with narrow scope: provider name, model identifier, timestamp, OpenClaw version, and pass or fail. Do not record prompt text if it contains private material, raw response data, request headers, environment output, or the key. A failed probe is useful evidence. It may mean the key is invalid, the provider is unavailable, the model is not permitted, the network boundary is wrong, or the configuration is incomplete. Do not “fix” a failed probe by disabling TLS, widening spend, or copying the key into a different file.

Use this ledger shape:

provider-check: provider=<name>; model=<id>; result=<pass|fail>; time=<UTC>
credential-storage: <masked prompt | approved SecretRef surface>; value recorded: no
workspace-search: no credential files added; result=<pass|fail>
raw-output-retained: no
next-action: <continue to Gateway verification | stop and revoke/escalate>

Understand the SecretRef boundary

SecretRefs are valuable because supported credentials need not live as plaintext in configuration or generated model files. The reviewed secrets guide describes in-memory runtime snapshots, opaque process-local sentinels, exact-value log redaction, and an audit check for plaintext residue. Those protections do not make arbitrary readable files safe. A copied .env, a retired auth profile, a backup, or a screenshot remains a credential until it is removed or isolated.

For this beginner lab, the useful rule is simpler than the full runtime design:

• keep the provider key out of the repository, workspace, task card, screenshots, and chat;
• use only a test credential with a fixed budget;
• keep the real channel disconnected;
• if exposure is possible, revoke first and investigate second;
• treat redaction as evidence hygiene, not revocation.

Scenario checkpoint

A screenshot captures the first characters of a key and is uploaded to a private issue tracker. The correct response is to stop the exercise, revoke the key at the provider, remove the image from every destination you control, search for other copies, and issue a replacement only if the lab still needs one. Cropping the screenshot does not prove that the original upload, browser cache, issue history, or local screenshot was destroyed.

A second scenario: the provider check fails, but onboarding writes a configuration file. Do not delete random fields or run onboarding repeatedly. Preserve the redacted failure result, inspect only through the documented status or audit commands, and use the official reset scope if you need to restart. A repeated failed probe can consume budget and leave several ambiguous config states.

Expected result, failure mode, and rollback

Expected result: one provider live check has a clear pass/fail result and the credential value is absent from the learner artifact. Failure mode: a key appears in a file, shell history, screenshot, log, or transcript; a provider check fails and the cause is unknown; or the budget is broader than the pre-flight card. Rollback: revoke the credential, remove confirmed unsafe copies, use the documented onboarding reset or uninstall path, and create a new test credential only after the boundary is clean. Record “revoked” and the time, not the key or provider account identifier.

The next lesson verifies the CLI and Gateway as separate layers. A provider pass does not mean a Gateway is reachable; a Gateway pass does not authorise a real channel.

Primary source receipt

• OpenClaw onboarding CLI, reviewed revision
• OpenClaw SecretRefs and plaintext boundaries, reviewed revision

Learner artifact: a redacted provider verification ledger. It demonstrates evidence discipline; it is not proof that a credential is safe for production use.