---
read_when:
- Gateway, 작업 영역, 인증, 채널, Skills에 대한 안내형 설정을 원하는 경우
summary: '`openclaw onboard`에 대한 CLI 참조(대화형 온보딩)'
title: 온보딩
x-i18n:
generated_at: "2026-07-04T20:28:42Z"
model: gpt-5.5
postprocess_version: locale-links-v1
provider: openai
source_hash: 99362cdca49929f7d05c2bf7bd8b0a55811b7ad6c618be90effb8869cd2ad839
source_path: cli/onboard.md
workflow: 16
---
# `openclaw onboard`
로컬 또는 원격 Gateway 설정을 위한 전체 가이드형 온보딩입니다. OpenClaw가 모델 인증, 워크스페이스, Gateway, 채널, Skills, 상태 확인을 하나의 흐름으로 안내하게 하려면 사용하세요.
## 관련 가이드
대화형 CLI 흐름 안내입니다.
OpenClaw 온보딩이 어떻게 함께 구성되는지 설명합니다.
출력, 내부 동작, 단계별 동작입니다.
비대화형 플래그와 스크립트 기반 설정입니다.
macOS 메뉴 막대 앱의 온보딩 흐름입니다.
## 예시
```bash
openclaw onboard
openclaw onboard --modern
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --flow import
openclaw onboard --import-from hermes --import-source ~/.hermes
openclaw onboard --skip-bootstrap
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
```
`--flow import`는 Hermes 같은 Plugin 소유 마이그레이션 공급자를 사용합니다. 새 OpenClaw 설정에서만 실행됩니다. 기존 구성, 자격 증명, 세션 또는 워크스페이스 메모리/ID 파일이 있으면 가져오기 전에 재설정하거나 새 설정을 선택하세요.
`--modern`은 Crestodian 대화형 온보딩 미리보기를 시작합니다. `--modern`이 없으면 `openclaw onboard`는 클래식 온보딩 흐름을 유지합니다.
대화형 터미널에서 하위 명령 없는 기본 `openclaw`는 구성 상태에 따라 라우팅됩니다.
- 활성 구성 파일이 없거나 작성된 설정이 없으면(비어 있거나 메타데이터만 있음) 이 클래식 온보딩 흐름을 시작합니다.
- 구성 파일이 있지만 검증에 실패하면 복구를 위해 [Crestodian](/ko/cli/crestodian)을 시작합니다.
- 구성 파일이 유효하면 일반 에이전트 TUI를 엽니다. 로컬로 열거나 도달 가능한 구성된 Gateway에 연결합니다. 구성된 설치에서는 TUI 안의 `/crestodian` 또는 `openclaw crestodian`으로 Crestodian에 접근하세요.
평문 `ws://`는 loopback, 사설 IP 리터럴, `.local`, Tailnet `*.ts.net` Gateway URL에 허용됩니다. 그 밖의 신뢰할 수 있는 사설 DNS 이름에는 온보딩 프로세스 환경에서 `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`을 설정하세요.
## 로캘
대화형 온보딩은 고정 설정 문구에 CLI 마법사 로캘을 사용합니다. 확인 순서는 다음과 같습니다.
1. `OPENCLAW_LOCALE`
2. `LC_ALL`
3. `LC_MESSAGES`
4. `LANG`
5. 영어 대체값
지원되는 마법사 로캘은 `en`, `zh-CN`, `zh-TW`입니다. 로캘 값은 `zh_CN.UTF-8` 같은 밑줄 또는 POSIX 접미사 형식을 사용할 수 있습니다. 제품 이름, 명령 이름, 구성 키, URL, 공급자 ID, 모델 ID, Plugin/채널 레이블은 그대로 유지됩니다.
예시:
```bash
OPENCLAW_LOCALE=zh-CN openclaw onboard
```
비대화형 사용자 지정 공급자:
```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-image-input
```
`--custom-api-key`는 비대화형 모드에서 선택 사항입니다. 생략하면 온보딩이 `CUSTOM_API_KEY`를 확인합니다.
OpenClaw는 일반적인 비전 모델 ID를 이미지 지원으로 자동 표시합니다. 알 수 없는 사용자 지정 비전 ID에는 `--custom-image-input`을 전달하고, 텍스트 전용 메타데이터를 강제하려면 `--custom-text-input`을 전달하세요.
`/v1/responses`는 지원하지만 `/v1/chat/completions`는 지원하지 않는 OpenAI 호환 엔드포인트에는 `--custom-compatibility openai-responses`를 사용하세요.
LM Studio는 비대화형 모드에서 공급자별 키 플래그도 지원합니다.
```bash
openclaw onboard --non-interactive \
--auth-choice lmstudio \
--custom-base-url "http://localhost:1234/v1" \
--custom-model-id "qwen/qwen3.5-9b" \
--lmstudio-api-key "$LM_API_TOKEN" \
--accept-risk
```
비대화형 Ollama:
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--custom-base-url "http://ollama-host:11434" \
--custom-model-id "qwen3.5:27b" \
--accept-risk
```
`--custom-base-url`의 기본값은 `http://127.0.0.1:11434`입니다. `--custom-model-id`는 선택 사항입니다. 생략하면 온보딩이 Ollama의 권장 기본값을 사용합니다. `kimi-k2.5:cloud` 같은 클라우드 모델 ID도 여기에서 작동합니다.
공급자 키를 평문 대신 참조로 저장:
```bash
openclaw onboard --non-interactive \
--auth-choice openai-api-key \
--secret-input-mode ref \
--accept-risk
```
`--secret-input-mode ref`를 사용하면 온보딩이 평문 키 값 대신 환경 기반 참조를 씁니다.
인증 프로필 기반 공급자의 경우 `keyRef` 항목을 쓰고, 사용자 지정 공급자의 경우 `models.providers..apiKey`를 env 참조로 씁니다(예: `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`).
비대화형 `ref` 모드 계약:
- 온보딩 프로세스 환경에 공급자 환경 변수를 설정하세요(예: `OPENAI_API_KEY`).
- 해당 환경 변수도 설정되어 있지 않다면 인라인 키 플래그(예: `--openai-api-key`)를 전달하지 마세요.
- 필요한 환경 변수 없이 인라인 키 플래그를 전달하면 온보딩은 안내와 함께 빠르게 실패합니다.
비대화형 모드의 Gateway 토큰 옵션:
- `--gateway-auth token --gateway-token `은 평문 토큰을 저장합니다.
- `--gateway-auth token --gateway-token-ref-env `은 `gateway.auth.token`을 env SecretRef로 저장합니다.
- `--gateway-token`과 `--gateway-token-ref-env`는 함께 사용할 수 없습니다.
- `--gateway-token-ref-env`에는 온보딩 프로세스 환경의 비어 있지 않은 환경 변수가 필요합니다.
- `--install-daemon`과 함께 사용할 때 토큰 인증에 토큰이 필요하면, SecretRef로 관리되는 Gateway 토큰은 검증되지만 supervisor 서비스 환경 메타데이터에 해석된 평문으로 유지되지 않습니다.
- `--install-daemon`과 함께 사용할 때 토큰 모드에 토큰이 필요하고 구성된 토큰 SecretRef가 해석되지 않으면, 온보딩은 해결 안내와 함께 닫힌 상태로 실패합니다.
- `--install-daemon`과 함께 사용할 때 `gateway.auth.token`과 `gateway.auth.password`가 모두 구성되어 있고 `gateway.auth.mode`가 설정되지 않았으면, 모드가 명시적으로 설정될 때까지 온보딩이 설치를 차단합니다.
- 로컬 온보딩은 구성에 `gateway.mode="local"`을 씁니다. 이후 구성 파일에 `gateway.mode`가 없으면 유효한 로컬 모드 단축 경로가 아니라 구성 손상 또는 불완전한 수동 편집으로 취급하세요.
- 로컬 온보딩은 선택한 설정 경로에 필요한 선택된 다운로드 가능 Plugin을 설치합니다.
- 원격 온보딩은 원격 Gateway에 대한 연결 정보만 쓰며 로컬 Plugin 패키지를 설치하지 않습니다.
- `--allow-unconfigured`는 별도의 Gateway 런타임 탈출구입니다. 온보딩이 `gateway.mode`를 생략해도 된다는 뜻이 아닙니다.
예시:
```bash
export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
--mode local \
--auth-choice skip \
--gateway-auth token \
--gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
--accept-risk
```
비대화형 로컬 Gateway 상태 확인:
- `--skip-health`를 전달하지 않으면 온보딩은 도달 가능한 로컬 Gateway를 기다린 뒤 성공적으로 종료합니다.
- `--install-daemon`은 관리형 Gateway 설치 경로를 먼저 시작합니다. 사용하지 않으면 예를 들어 `openclaw gateway run`처럼 로컬 Gateway가 이미 실행 중이어야 합니다.
- 자동화에서 구성/워크스페이스/부트스트랩 쓰기만 원한다면 `--skip-health`를 사용하세요.
- 워크스페이스 파일을 직접 관리한다면 `--skip-bootstrap`을 전달해 `agents.defaults.skipBootstrap: true`를 설정하고 `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` 생성을 건너뛰세요.
- 네이티브 Windows에서 `--install-daemon`은 먼저 예약된 작업을 시도하고, 작업 생성이 거부되면 사용자별 시작 폴더 로그인 항목으로 대체합니다.
참조 모드의 대화형 온보딩 동작:
- 프롬프트가 표시되면 **비밀 참조 사용**을 선택하세요.
- 그런 다음 다음 중 하나를 선택하세요.
- 환경 변수
- 구성된 비밀 공급자(`file` 또는 `exec`)
- 온보딩은 참조를 저장하기 전에 빠른 사전 검증을 수행합니다.
- 검증이 실패하면 온보딩이 오류를 표시하고 다시 시도할 수 있게 합니다.
### 비대화형 Z.AI 엔드포인트 선택
`--auth-choice zai-api-key`는 키에 가장 적합한 Z.AI 엔드포인트와 모델을 자동 감지합니다. Coding Plan 엔드포인트는 `zai/glm-5.2`를 선호하고, 일반 API 엔드포인트는 `zai/glm-5.1`을 사용합니다. Coding Plan 엔드포인트를 강제하려면 `zai-coding-global` 또는 `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
```
비대화형 Mistral 예시:
```bash
openclaw onboard --non-interactive \
--auth-choice mistral-api-key \
--mistral-api-key "$MISTRAL_API_KEY"
```
## 추가 비대화형 플래그
토큰 기반 모델 인증(비대화형, `--auth-choice token`과 함께 사용):
- `--token-provider ` — 토큰 공급자 ID입니다. 어느 공급자가 토큰을 발급하는지 식별합니다.
- `--token ` — 모델 인증용 토큰 값입니다.
- `--token-profile-id ` — 인증 프로필 ID입니다. 일반 토큰 저장의 기본값은 `:manual`입니다. 공급자 소유 설정 흐름은 `anthropic:default` 같은 자체 기본값을 사용할 수 있습니다.
- `--token-expires-in ` — 선택적 토큰 만료 기간입니다(예: `365d`, `12h`).
Cloudflare AI Gateway(비대화형):
- `--cloudflare-ai-gateway-account-id ` — Cloudflare AI Gateway를 통한 라우팅용 Cloudflare 계정 ID입니다.
- `--cloudflare-ai-gateway-gateway-id ` — Cloudflare AI Gateway ID입니다.
Daemon 설치 제어:
- `--no-install-daemon` — Gateway 서비스 설치를 명시적으로 건너뜁니다.
- `--skip-daemon` — `--no-install-daemon`의 별칭입니다.
UI 및 후크 설정 제어:
- `--skip-ui` — 온보딩 중 Control UI / TUI 프롬프트를 건너뜁니다.
- `--skip-hooks` — 온보딩 중 Webhook / 후크 설정 프롬프트를 건너뜁니다.
출력 억제:
- `--suppress-gateway-token-output` — 토큰을 포함하는 Gateway/UI 출력(토큰 힌트, 내장 토큰이 있는 자동 로그인 URL, 자동 Control UI 실행)을 억제합니다. 공유 터미널 및 CI 환경에서 유용합니다.
## 흐름 참고 사항
- `quickstart`: 최소 프롬프트, Gateway 토큰을 자동 생성합니다.
- `manual`: 포트, 바인드, 인증에 대한 전체 프롬프트입니다(`advanced`의 별칭).
- `import`: 감지된 마이그레이션 공급자를 실행하고, 계획을 미리 보여준 다음 확인 후 적용합니다.
인증 선택이 선호 공급자를 의미하면 온보딩은 기본 모델 및 허용 목록 선택기를 해당 공급자로 사전 필터링합니다. Volcengine과 BytePlus의 경우 Coding Plan 변형(`volcengine-plan/*`, `byteplus-plan/*`)도 일치시킵니다.
선호 공급자 필터 결과 아직 로드된 모델이 없으면, 온보딩은 선택기를 비워 두는 대신 필터링되지 않은 카탈로그로 대체합니다.
일부 웹 검색 공급자는 공급자별 후속 프롬프트를 트리거합니다.
- **Grok**은 동일한 xAI OAuth 프로필 또는 API 키와 `x_search` 모델 선택을 사용하는 선택적 `x_search` 설정을 제공할 수 있습니다.
- **Kimi**는 Moonshot API 지역(`api.moonshot.ai` 대 `api.moonshot.cn`)과 기본 Kimi 웹 검색 모델을 물을 수 있습니다.
- 로컬 온보딩 DM 범위 동작: [CLI 설정 참조](/ko/start/wizard-cli-reference#outputs-and-internals).
- 가장 빠른 첫 채팅: `openclaw dashboard`(Control UI, 채널 설정 없음).
- 사용자 지정 공급자: 목록에 없는 호스팅 공급자를 포함해 OpenAI 또는 Anthropic 호환 엔드포인트에 연결합니다. 자동 감지하려면 Unknown을 사용하세요.
- Hermes 상태가 감지되면 온보딩은 마이그레이션 흐름을 제공합니다. 드라이런 계획, 덮어쓰기 모드, 보고서, 정확한 매핑에는 [마이그레이션](/ko/cli/migrate)을 사용하세요.
## 일반적인 후속 명령
```bash
openclaw channels add
openclaw configure
openclaw agents add
```
동일한 안내형 온보딩 진입점으로 `openclaw setup`을 사용하세요. 기준 구성/워크스페이스만 필요한 경우 `openclaw setup --baseline`을 사용하고, 이후 대상 변경에는 `openclaw configure`를, 채널 전용 설정에는 `openclaw channels add`를 사용하세요.
`--json`은 비대화형 모드를 의미하지 않습니다. 스크립트에는 `--non-interactive`를 사용하세요.