English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Technical reference

온보딩 참고 자료

openclaw onboard의 전체 참조 문서입니다. 상위 수준 개요는 온보딩(CLI)를 참조하세요.

흐름 세부 정보(로컬 모드)

  • 기존 구성 감지

    • ~/.openclaw/openclaw.json이 있으면 현재 값 유지, 검토 및 업데이트, 또는 설정 전 재설정을 선택합니다.
    • 온보딩을 다시 실행해도 명시적으로 재설정을 선택하지 않는 한 아무것도 지우지 않습니다 (--reset을 전달한 경우도 해당).
    • CLI --reset의 기본값은 config+creds+sessions입니다. 작업 공간도 제거하려면 --reset-scope full을 사용하세요.
    • 구성이 유효하지 않거나 레거시 키를 포함하면 마법사가 중지되고 계속하기 전에 openclaw doctor를 실행하라고 요청합니다.
    • 재설정은 trash를 사용하며(rm은 절대 사용하지 않음) 다음 범위를 제공합니다.
      • 구성만
      • 구성 + 자격 증명 + 세션
      • 전체 재설정(작업 공간도 제거)

  • 모델/인증

    • Anthropic API 키: 있으면 ANTHROPIC_API_KEY를 사용하고, 없으면 키를 입력하라는 메시지를 표시한 뒤 daemon 사용을 위해 저장합니다.
    • Anthropic API 키: 온보딩/구성에서 선호되는 Anthropic 어시스턴트 선택지입니다.
    • Anthropic setup-token: OpenClaw는 이제 사용 가능한 경우 Claude CLI 재사용을 선호하지만, 온보딩/구성에서 여전히 사용할 수 있습니다.
    • OpenAI Code (Codex) 구독(OAuth): 브라우저 흐름입니다. code#state를 붙여 넣습니다.
      • 모델이 설정되지 않았거나 이미 OpenAI 계열인 경우 Codex 런타임을 통해 agents.defaults.model을 openai/gpt-5.5로 설정합니다.
    • OpenAI Code (Codex) 구독(기기 페어링): 수명이 짧은 기기 코드를 사용하는 브라우저 페어링 흐름입니다.
      • 모델이 설정되지 않았거나 이미 OpenAI 계열인 경우 Codex 런타임을 통해 agents.defaults.model을 openai/gpt-5.5로 설정합니다.
    • OpenAI API 키: 있으면 OPENAI_API_KEY를 사용하고, 없으면 키를 입력하라는 메시지를 표시한 뒤 인증 프로필에 저장합니다.
      • 모델이 설정되지 않았거나 openai/* 또는 레거시 Codex 모델 참조인 경우 agents.defaults.model을 openai/gpt-5.5로 설정합니다.
    • xAI (Grok) OAuth / API 키: 선택 시 xAI OAuth로 로그인하거나, API 키 경로에서는 XAI_API_KEY를 입력하라는 메시지를 표시하고 xAI를 모델 제공자로 구성합니다.
    • OpenCode: OPENCODE_API_KEY(또는 OPENCODE_ZEN_API_KEY, https://opencode.ai/auth 에서 발급)를 입력하라는 메시지를 표시하고 Zen 또는 Go 카탈로그를 선택할 수 있게 합니다.
    • Ollama: 먼저 Cloud + Local, Cloud only, 또는 Local only를 제공합니다. Cloud only는 OLLAMA_API_KEY를 입력하라는 메시지를 표시하고 https://ollama.com을 사용합니다. 호스트 기반 모드는 Ollama 기본 URL을 입력하라는 메시지를 표시하고, 사용 가능한 모델을 검색하며, 필요한 경우 선택한 로컬 모델을 자동으로 가져옵니다. Cloud + Local은 해당 Ollama 호스트가 클라우드 접근에 로그인되어 있는지도 확인합니다.
    • 자세한 내용: Ollama
    • API 키: 키를 저장해 줍니다.
    • Vercel AI Gateway(다중 모델 프록시): AI_GATEWAY_API_KEY를 입력하라는 메시지를 표시합니다.
    • 자세한 내용: Vercel AI Gateway
    • Cloudflare AI Gateway: 계정 ID, Gateway ID, CLOUDFLARE_AI_GATEWAY_API_KEY를 입력하라는 메시지를 표시합니다.
    • 자세한 내용: Cloudflare AI Gateway
    • MiniMax: 구성이 자동으로 작성됩니다. 호스팅 기본값은 MiniMax-M3입니다. API 키 설정은 minimax/...를 사용하고, OAuth 설정은 minimax-portal/...을 사용합니다.
    • 자세한 내용: MiniMax
    • StepFun: 중국 또는 글로벌 엔드포인트의 StepFun 표준 또는 Step Plan에 대해 구성이 자동으로 작성됩니다.
    • 현재 표준에는 step-3.5-flash가 포함되며, Step Plan에는 step-3.5-flash-2603도 포함됩니다.
    • 자세한 내용: StepFun
    • Synthetic(Anthropic 호환): SYNTHETIC_API_KEY를 입력하라는 메시지를 표시합니다.
    • 자세한 내용: Synthetic
    • Moonshot (Kimi K2): 구성이 자동으로 작성됩니다.
    • Kimi Coding: 구성이 자동으로 작성됩니다.
    • 자세한 내용: Moonshot AI (Kimi + Kimi Coding)
    • 건너뛰기: 아직 인증을 구성하지 않습니다.
    • 감지된 옵션에서 기본 모델을 선택하거나 제공자/모델을 수동으로 입력합니다. 최상의 품질과 더 낮은 프롬프트 인젝션 위험을 위해 제공자 스택에서 사용할 수 있는 가장 강력한 최신 세대 모델을 선택하세요.
    • 온보딩은 모델 검사를 실행하고 구성된 모델을 알 수 없거나 인증이 누락된 경우 경고합니다.
    • API 키 저장 모드의 기본값은 일반 텍스트 인증 프로필 값입니다. 대신 환경 변수 기반 참조를 저장하려면 --secret-input-mode ref를 사용하세요(예: keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }).
    • 인증 프로필은 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json(API 키 + OAuth)에 있습니다. ~/.openclaw/credentials/oauth.json은 레거시 가져오기 전용입니다.
    • 자세한 내용: /concepts/oauth

  • 작업 공간

    • 기본값은 ~/.openclaw/workspace입니다(구성 가능).
    • 에이전트 부트스트랩 의식에 필요한 작업 공간 파일을 시드합니다.
    • 전체 작업 공간 레이아웃 + 백업 가이드: 에이전트 작업 공간

  • Gateway

    • 포트, 바인드, 인증 모드, Tailscale 노출.
    • 인증 권장 사항: 루프백에서도 로컬 WS 클라이언트가 반드시 인증하도록 토큰을 유지하세요.
    • 토큰 모드에서 대화형 설정은 다음을 제공합니다.
      • 일반 텍스트 토큰 생성/저장(기본값)
      • SecretRef 사용(옵트인)
      • 빠른 시작은 온보딩 프로브/대시보드 부트스트랩을 위해 env, file, exec 제공자 전반에서 기존 gateway.auth.token SecretRef를 재사용합니다.
      • 해당 SecretRef가 구성되어 있지만 확인할 수 없는 경우, 온보딩은 런타임 인증을 조용히 약화시키는 대신 명확한 수정 메시지와 함께 일찍 실패합니다.
    • 비밀번호 모드에서 대화형 설정은 일반 텍스트 또는 SecretRef 저장도 지원합니다.
    • 비대화형 토큰 SecretRef 경로: --gateway-token-ref-env &lt;ENV_VAR&gt;.
      • 온보딩 프로세스 환경에 비어 있지 않은 환경 변수가 필요합니다.
      • --gateway-token과 함께 사용할 수 없습니다.
    • 모든 로컬 프로세스를 완전히 신뢰하는 경우에만 인증을 비활성화하세요.
    • 루프백이 아닌 바인드는 여전히 인증이 필요합니다.

  • 채널

    • WhatsApp: 선택적 QR 로그인.
    • Telegram: 봇 토큰.
    • Discord: 봇 토큰.
    • Google Chat: 서비스 계정 JSON + webhook 대상.
    • Mattermost (plugin): 봇 토큰 + 기본 URL.
    • Signal: 선택적 signal-cli 설치 + 계정 구성.
    • iMessage: imsg CLI 경로 + Messages DB 접근. Gateway가 Mac 외부에서 실행될 때는 SSH 래퍼를 사용하세요.
    • DM 보안: 기본값은 페어링입니다. 첫 DM은 코드를 보냅니다. openclaw pairing approve <channel> <code>로 승인하거나 허용 목록을 사용하세요.

  • 웹 검색

    • Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, Tavily 같은 지원 제공자를 선택하거나 건너뜁니다.
    • API 기반 제공자는 빠른 설정을 위해 환경 변수나 기존 구성을 사용할 수 있습니다. 키가 필요 없는 제공자는 대신 해당 제공자별 필수 조건을 사용합니다.
    • --skip-search로 건너뜁니다.
    • 나중에 구성: openclaw configure --section web.

  • Daemon 설치

    • macOS: LaunchAgent
      • 로그인된 사용자 세션이 필요합니다. 헤드리스의 경우 사용자 지정 LaunchDaemon을 사용하세요(제공되지 않음).
    • Linux(및 WSL2를 통한 Windows): systemd 사용자 유닛
      • 온보딩은 로그아웃 후에도 Gateway가 계속 실행되도록 loginctl enable-linger <user>를 통해 lingering 활성화를 시도합니다.
      • sudo를 요청할 수 있습니다(/var/lib/systemd/linger에 씀). 먼저 sudo 없이 시도합니다.
    • 런타임 선택: Node(권장, WhatsApp/Telegram에 필요). Bun은 권장되지 않습니다.
    • 토큰 인증에 토큰이 필요하고 gateway.auth.token이 SecretRef로 관리되는 경우, daemon 설치는 이를 검증하지만 확인된 일반 텍스트 토큰 값을 supervisor 서비스 환경 메타데이터에 지속하지 않습니다.
    • 토큰 인증에 토큰이 필요하고 구성된 토큰 SecretRef를 확인할 수 없는 경우, daemon 설치는 실행 가능한 안내와 함께 차단됩니다.
    • gateway.auth.token과 gateway.auth.password가 모두 구성되어 있고 gateway.auth.mode가 설정되지 않은 경우, 모드를 명시적으로 설정할 때까지 daemon 설치가 차단됩니다.

  • 상태 검사

    • 필요한 경우 Gateway를 시작하고 openclaw health를 실행합니다.
    • 팁: openclaw status --deep은 지원되는 경우 채널 프로브를 포함하여 라이브 gateway 상태 프로브를 상태 출력에 추가합니다(도달 가능한 gateway 필요).

  • Skills(권장)

    • 사용 가능한 Skills를 읽고 요구 사항을 확인합니다.
    • 노드 관리자를 선택할 수 있게 합니다: npm / pnpm(bun은 권장되지 않음).
    • 선택적 종속성을 설치합니다(일부는 macOS에서 Homebrew 사용).

  • 완료

    • Terminal, Browser 또는 나중에를 위한 에이전트를 어떻게 부화시키시겠습니까? 프롬프트를 포함한 요약 + 다음 단계.

    • 비대화형 모드

    온보딩을 자동화하거나 스크립트화하려면 --non-interactive를 사용하세요.

    bash
    openclaw onboard --non-interactive \  --mode local \  --auth-choice apiKey \  --anthropic-api-key "$ANTHROPIC_API_KEY" \  --gateway-port 18789 \  --gateway-bind loopback \  --install-daemon \  --daemon-runtime node \  --skip-skills

    머신이 읽을 수 있는 요약을 원하면 --json을 추가하세요.

    비대화형 모드에서 Gateway 토큰 SecretRef:

    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

    --gateway-token과 --gateway-token-ref-env는 서로 배타적입니다.

    제공자별 명령 예시는 CLI 자동화에 있습니다. 플래그 의미와 단계 순서는 이 참조 페이지를 사용하세요.

    에이전트 추가(비대화형)

    bash
    openclaw agents add work \  --workspace ~/.openclaw/workspace-work \  --model openai/gpt-5.5 \  --bind whatsapp:biz \  --non-interactive \  --json

    Gateway 마법사 RPC

    Gateway는 RPC(wizard.start, wizard.next, wizard.cancel, wizard.status)를 통해 온보딩 흐름을 노출합니다. 클라이언트(macOS 앱, Control UI)는 온보딩 로직을 다시 구현하지 않고 단계를 렌더링할 수 있습니다.

    Signal 설정(signal-cli)

    온보딩은 GitHub 릴리스에서 signal-cli를 설치할 수 있습니다.

    • 적절한 릴리스 애셋을 다운로드합니다.
    • ~/.openclaw/tools/signal-cli/<version>/ 아래에 저장합니다.
    • 구성에 channels.signal.cliPath를 씁니다.

    참고:

    • JVM 빌드에는 Java 21이 필요합니다.
    • 사용 가능한 경우 네이티브 빌드를 사용합니다.
    • Windows는 WSL2를 사용합니다. signal-cli 설치는 WSL 내부의 Linux 흐름을 따릅니다.

    마법사가 쓰는 내용

    ~/.openclaw/openclaw.json의 일반적인 필드:

    • agents.defaults.workspace
    • agents.defaults.model / models.providers(Minimax를 선택한 경우)
    • tools.profile(설정되지 않은 경우 로컬 온보딩 기본값은 "coding"이며, 기존의 명시적 값은 유지됩니다)
    • gateway.*(모드, 바인드, 인증, tailscale)
    • session.dmScope(동작 세부 정보: CLI 설정 참고 자료)
    • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
    • 프롬프트 중에 옵트인할 때의 채널 허용 목록(Slack/Discord/Matrix/Microsoft Teams)(가능한 경우 이름은 ID로 확인됩니다).
    • skills.install.nodeManager
      • setup --node-manager는 npm, pnpm 또는 bun을 허용합니다.
      • 수동 구성에서는 skills.install.nodeManager를 직접 설정하여 여전히 yarn을 사용할 수 있습니다.
    • wizard.lastRunAt
    • wizard.lastRunVersion
    • wizard.lastRunCommit
    • wizard.lastRunCommand
    • wizard.lastRunMode

    openclaw agents add는 agents.list[]와 선택적 bindings를 씁니다.

    WhatsApp 자격 증명은 ~/.openclaw/credentials/whatsapp/<accountId>/ 아래에 둡니다. 세션은 ~/.openclaw/agents/<agentId>/sessions/ 아래에 저장됩니다.

    일부 채널은 plugins로 제공됩니다. 설정 중 하나를 선택하면 온보딩에서 구성하기 전에 설치(npm 또는 로컬 경로)를 요청합니다.

    관련 문서

    Was this useful?
    On this page

    On this page