mirror of
https://github.com/openclaw/openclaw.git
synced 2026-03-13 11:00:50 +00:00
449511484d
* fix(gateway): allow ws:// to RFC 1918 private network addresses resolve ws-private-network conflicts * gateway: keep ws security strict-by-default with private opt-in * gateway: apply private ws opt-in in connection detail guard * gateway: apply private ws opt-in in websocket client * onboarding: gate private ws urls behind explicit opt-in * gateway tests: enforce strict ws defaults with private opt-in * onboarding tests: validate private ws opt-in behavior * gateway client tests: cover private ws env override * gateway call tests: cover private ws env override * changelog: add ws strict-default security entry for pr 28670 * docs(onboard): document private ws break-glass env * docs(gateway): add private ws env to remote guide * docs(docker): add private ws break-glass env var * docs(security): add private ws break-glass guidance * docs(config): document OPENCLAW_ALLOW_PRIVATE_WS * Update CHANGELOG.md * gateway: normalize private-ws host classification * test(gateway): cover non-unicast ipv6 private-ws edges * changelog: rename insecure private ws break-glass env * docs(onboard): rename insecure private ws env * docs(gateway): rename insecure private ws env in config reference * docs(gateway): rename insecure private ws env in remote guide * docs(security): rename insecure private ws env * docs(docker): rename insecure private ws env * test(onboard): rename insecure private ws env * onboard: rename insecure private ws env * test(gateway): rename insecure private ws env in call tests * gateway: rename insecure private ws env in call flow * test(gateway): rename insecure private ws env in client tests * gateway: rename insecure private ws env in client * docker: pass insecure private ws env to services * docker-setup: persist insecure private ws env --------- Co-authored-by: Vincent Koc <vincentkoc@ieee.org>
117 lines
3.8 KiB
Markdown
117 lines
3.8 KiB
Markdown
---
|
|
summary: "CLI reference for `openclaw onboard` (interactive onboarding wizard)"
|
|
read_when:
|
|
- You want guided setup for gateway, workspace, auth, channels, and skills
|
|
title: "onboard"
|
|
---
|
|
|
|
# `openclaw onboard`
|
|
|
|
Interactive onboarding wizard (local or remote Gateway setup).
|
|
|
|
## Related guides
|
|
|
|
- CLI onboarding hub: [Onboarding Wizard (CLI)](/start/wizard)
|
|
- Onboarding overview: [Onboarding Overview](/start/onboarding-overview)
|
|
- CLI onboarding reference: [CLI Onboarding Reference](/start/wizard-cli-reference)
|
|
- CLI automation: [CLI Automation](/start/wizard-cli-automation)
|
|
- macOS onboarding: [Onboarding (macOS App)](/start/onboarding)
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
openclaw onboard
|
|
openclaw onboard --flow quickstart
|
|
openclaw onboard --flow manual
|
|
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
|
|
```
|
|
|
|
For plaintext private-network `ws://` targets (trusted networks only), set
|
|
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` in the onboarding process environment.
|
|
|
|
Non-interactive custom provider:
|
|
|
|
```bash
|
|
openclaw onboard --non-interactive \
|
|
--auth-choice custom-api-key \
|
|
--custom-base-url "https://llm.example.com/v1" \
|
|
--custom-model-id "foo-large" \
|
|
--custom-api-key "$CUSTOM_API_KEY" \
|
|
--secret-input-mode plaintext \
|
|
--custom-compatibility openai
|
|
```
|
|
|
|
`--custom-api-key` is optional in non-interactive mode. If omitted, onboarding checks `CUSTOM_API_KEY`.
|
|
|
|
Store provider keys as refs instead of plaintext:
|
|
|
|
```bash
|
|
openclaw onboard --non-interactive \
|
|
--auth-choice openai-api-key \
|
|
--secret-input-mode ref \
|
|
--accept-risk
|
|
```
|
|
|
|
With `--secret-input-mode ref`, onboarding writes env-backed refs instead of plaintext key values.
|
|
For auth-profile backed providers this writes `keyRef` entries; for custom providers this writes `models.providers.<id>.apiKey` as an env ref (for example `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`).
|
|
|
|
Non-interactive `ref` mode contract:
|
|
|
|
- Set the provider env var in the onboarding process environment (for example `OPENAI_API_KEY`).
|
|
- Do not pass inline key flags (for example `--openai-api-key`) unless that env var is also set.
|
|
- If an inline key flag is passed without the required env var, onboarding fails fast with guidance.
|
|
|
|
Interactive onboarding behavior with reference mode:
|
|
|
|
- Choose **Use secret reference** when prompted.
|
|
- Then choose either:
|
|
- Environment variable
|
|
- Configured secret provider (`file` or `exec`)
|
|
- Onboarding performs a fast preflight validation before saving the ref.
|
|
- If validation fails, onboarding shows the error and lets you retry.
|
|
|
|
Non-interactive Z.AI endpoint choices:
|
|
|
|
Note: `--auth-choice zai-api-key` now auto-detects the best Z.AI endpoint for your key (prefers the general API with `zai/glm-5`).
|
|
If you specifically want the GLM Coding Plan endpoints, pick `zai-coding-global` or `zai-coding-cn`.
|
|
|
|
```bash
|
|
# Promptless endpoint selection
|
|
openclaw onboard --non-interactive \
|
|
--auth-choice zai-coding-global \
|
|
--zai-api-key "$ZAI_API_KEY"
|
|
|
|
# Other Z.AI endpoint choices:
|
|
# --auth-choice zai-coding-cn
|
|
# --auth-choice zai-global
|
|
# --auth-choice zai-cn
|
|
```
|
|
|
|
Non-interactive Mistral example:
|
|
|
|
```bash
|
|
openclaw onboard --non-interactive \
|
|
--auth-choice mistral-api-key \
|
|
--mistral-api-key "$MISTRAL_API_KEY"
|
|
```
|
|
|
|
Flow notes:
|
|
|
|
- `quickstart`: minimal prompts, auto-generates a gateway token.
|
|
- `manual`: full prompts for port/bind/auth (alias of `advanced`).
|
|
- Local onboarding DM scope behavior: [CLI Onboarding Reference](/start/wizard-cli-reference#outputs-and-internals).
|
|
- Fastest first chat: `openclaw dashboard` (Control UI, no channel setup).
|
|
- Custom Provider: connect any OpenAI or Anthropic compatible endpoint,
|
|
including hosted providers not listed. Use Unknown to auto-detect.
|
|
|
|
## Common follow-up commands
|
|
|
|
```bash
|
|
openclaw configure
|
|
openclaw agents add <name>
|
|
```
|
|
|
|
<Note>
|
|
`--json` does not imply non-interactive mode. Use `--non-interactive` for scripts.
|
|
</Note>
|