Installer internals
기준일: 2026-07-26
공식 기준: Installer internals
Installer internals 문서는 OpenClaw 공식 문서(install/installer)를 한국어로 정리한 가이드입니다. How the installer scripts work (install.sh, install-cli.sh, install.ps1), flags, and automation 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.
핵심 요약
How the installer scripts work (install.sh, install-cli.sh, install.ps1), flags, and automation
한국어 가이드 범위: install/installer 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.
문서 구성
공식 문서의 주요 섹션은 다음과 같습니다.
- Quick commands
- install.sh
- Flow (install.sh)
- Source checkout detection
- Examples (install.sh)
- install-cli.sh
- Flow (install-cli.sh)
- Examples (install-cli.sh)
- install.ps1
- Flow (install.ps1)
- Examples (install.ps1)
- CI and automation
- 트러블슈팅
- 관련 문서
상세 내용
본문
OpenClaw ships three installer scripts, served from openclaw.ai.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Script | Platform | What it does |
|---|---|---|
install.sh |
macOS / Linux / WSL | Installs Node if needed, installs OpenClaw via npm (default) or git, can run onboarding. |
install-cli.sh |
macOS / Linux / WSL | Installs Node + OpenClaw into a local prefix (~/.openclaw) via npm or git. No root required. |
install.ps1 |
Windows (PowerShell) | Installs Node if needed, installs OpenClaw via npm (default) or git, can run onboarding. |
Quick commands
If install succeeds but openclaw is not found in a new terminal, see Node.js troubleshooting.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help
install.sh
Recommended for most interactive installs on macOS/Linux/WSL.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Flow (install.sh)
Supports macOS and Linux (including WSL).
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
npmmethod (default): global npm installgitmethod: clone/update repo, install deps with pnpm, build, then install wrapper at~/.local/bin/openclaw- Resolves the just-installed
openclawbinary for follow-up commands - For an unconfigured install, starts onboarding before doctor or gateway probes. With
--no-onboardor no TTY, it prints the command to finish setup later. - For a configured install, refreshes and restarts a loaded gateway service best-effort and runs doctor. Upgrades update plugins when possible, or print the manual command in a headless prompt-enabled run.
- When
--verifyruns, it checks the installed version and checks gateway health only after configuration exists.
Source checkout detection
If run inside an OpenClaw checkout (package.json + pnpm-workspace.yaml), the script offers:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
- use checkout (
git), or - use global install (
npm)
Examples (install.sh)
| Flag | Description |
|---|---|
--install-method | --method npm|git |
Choose install method (default: npm) |
--npm |
Shortcut for npm method |
--git | --github |
Shortcut for git method |
--version <version|dist-tag|spec> |
npm version, dist-tag, or package spec (default: latest) |
--beta |
Use beta dist-tag if available, else fall back to latest |
--git-dir | --dir <path> |
Checkout directory (default: ~/openclaw) |
--no-git-update |
Skip git pull for existing checkout |
--no-prompt |
Disable prompts |
--no-onboard |
Skip onboarding |
--onboard |
Enable onboarding |
--verify |
Run a post-install smoke verify (--version, gateway health if loaded) |
--dry-run |
Print actions without applying changes |
--verbose |
Enable debug output (set -x, npm notice-level logs) |
--help | -h |
Show usage |
| Variable | Description |
|---|---|
OPENCLAW_INSTALL_METHOD=git|npm |
Install method |
OPENCLAW_VERSION=latest|next|<semver>|<spec> |
npm version, dist-tag, or package spec |
OPENCLAW_BETA=0|1 |
Use beta if available |
OPENCLAW_HOME=<path> |
Base directory for OpenClaw state and default git/onboarding paths |
OPENCLAW_GIT_DIR=<path> |
Checkout directory |
OPENCLAW_GIT_UPDATE=0|1 |
Toggle git updates |
OPENCLAW_NO_PROMPT=1 |
Disable prompts |
OPENCLAW_VERIFY_INSTALL=1 |
Run the post-install smoke verify |
OPENCLAW_NO_ONBOARD=1 |
Skip onboarding |
OPENCLAW_DRY_RUN=1 |
Dry run mode |
OPENCLAW_VERBOSE=1 |
Debug mode |
OPENCLAW_NPM_LOGLEVEL=error|warn|notice |
npm log level (default: error, hides npm deprecation noise) |
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git --version main
install-cli.sh
Designed for environments where you want everything under a local prefix (default ~/.openclaw) and no system Node dependency. Supports npm installs by default, plus git-checkout installs under the same prefix flow.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Flow (install-cli.sh)
Downloads a pinned supported Node LTS tarball (the version is embedded in the script and updated independently, default 24.15.0) to /tools/node-v and verifies SHA-256. Linux ARMv7 uses Node 22.22.3 because official Node 24+ ARMv7 binaries are unavailable. On Alpine/musl Linux, where Node does not publish compatible tarballs for the pinned runtime, installs nodejs and npm with apk, then verifies both Node and the actual linked SQLite library. Current stable Alpine package streams may still link vulnerable SQLite even with a new-enough Node; use an official node:24-alpine container or a glibc-based host when the safety check rejects the package.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
npmmethod (default): installs under the prefix with npm, then writes wrapper to<prefix>/bin/openclawgitmethod: clones/updates a checkout (default~/openclaw) and still writes the wrapper to<prefix>/bin/openclaw
Examples (install-cli.sh)
openclaw@main and other GitHub source specs are not valid --version targets for npm installs. Use --install-method git --version main instead.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Flag | Description |
|---|---|
--prefix <path> |
Install prefix (default: ~/.openclaw) |
--install-method | --method npm|git |
Choose install method (default: npm) |
--npm |
Shortcut for npm method |
--git | --github |
Shortcut for git method |
--git-dir | --dir <path> |
Git checkout directory (default: ~/openclaw) |
--version <ver> |
OpenClaw version or dist-tag (default: latest) |
--node-version <ver> |
Node version (default: 24.15.0; 22.22.3 on Linux ARMv7) |
--json |
Emit NDJSON events |
--onboard |
Run openclaw onboard after install |
--no-onboard |
Skip onboarding (default) |
--set-npm-prefix |
On Linux, force npm prefix to ~/.npm-global if current prefix is not writable |
--help | -h |
Show usage |
| Variable | Description |
|---|---|
OPENCLAW_PREFIX=<path> |
Install prefix |
OPENCLAW_INSTALL_METHOD=git|npm |
Install method |
OPENCLAW_VERSION=<ver> |
OpenClaw version or dist-tag |
OPENCLAW_NODE_VERSION=<ver> |
Node version |
OPENCLAW_HOME=<path> |
Base directory for OpenClaw state and default git/onboarding paths |
OPENCLAW_GIT_DIR=<path> |
Git checkout directory for git installs |
OPENCLAW_GIT_UPDATE=0|1 |
Toggle git updates for existing checkouts |
OPENCLAW_NO_ONBOARD=1 |
Skip onboarding |
OPENCLAW_NPM_LOGLEVEL=error|warn|notice |
npm log level (default: error) |
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --install-method git --git-dir ~/openclaw
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
install.ps1
이 섹션의 세부 항목은 공식 문서 install.ps1를 참고하세요.
Flow (install.ps1)
If missing, attempts install via winget, then Chocolatey, then Scoop. If no package manager is available, the script downloads the official Node.js 24 Windows zip into %LOCALAPPDATA%\OpenClaw\deps\portable-node and adds it to the current process and user PATH. Node 22.22.3+, Node 24.15+, and Node 25.9+ are supported; Node 23 is unsupported.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
npmmethod (default): global npm install using the selected-Tag, launched from a writable installer temp directory so shells opened in protected folders such asC:\still workgitmethod: clone/update repo, install/build with pnpm, and install wrapper at%USERPROFILE%\.local\bin\openclaw.cmd. If Git is missing, the script bootstraps user-local MinGit under%LOCALAPPDATA%\OpenClaw\deps\portable-gitand adds it to the current process and user PATH.- Adds needed bin directory to user PATH when possible
- Refreshes a loaded gateway service best-effort (
openclaw gateway install --force, then restart) - Runs
openclaw doctor --non-interactiveon upgrades and git installs (best effort)
Examples (install.ps1)
If -InstallMethod git is used and Git is missing, the script tries a user-local MinGit bootstrap before printing the Git for Windows link.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Flag | Description |
|---|---|
-InstallMethod npm|git |
Install method (default: npm) |
-Tag <tag|version|spec> |
npm dist-tag, version, or package spec (default: latest) |
-GitDir <path> |
Checkout directory (default: %USERPROFILE%\openclaw) |
-NoOnboard |
Skip onboarding |
-NoGitUpdate |
Skip git pull |
-DryRun |
Print actions only |
| Variable | Description |
|---|---|
OPENCLAW_INSTALL_METHOD=git|npm |
Install method |
OPENCLAW_GIT_DIR=<path> |
Checkout directory |
OPENCLAW_NO_ONBOARD=1 |
Skip onboarding |
OPENCLAW_GIT_UPDATE=0 |
Disable git pull |
OPENCLAW_DRY_RUN=1 |
Dry run mode |
iwr -useb https://openclaw.ai/install.ps1 | iex
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -Tag main
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw"
CI and automation
Use non-interactive flags/env vars for predictable runs.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard
OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
트러블슈팅
Git is required for the git install method. For npm installs, Git is still checked/installed to avoid spawn git ENOENT failures when dependencies use git URLs.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
관련 문서
주요 항목:
- Install overview
- Updating
- Uninstall
실습 체크리스트
- 공식 문서와 로컬 버전을 대조합니다:
https://docs.openclaw.ai/install/installer - 관련 CLI는
openclaw --help및 하위 명령--help로 옵션을 확인합니다. - 설정 변경 시
openclaw config/openclaw doctor로 유효성을 검사합니다. - Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.
자주 쓰는 명령·설정 예시
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help
iwr -useb https://openclaw.ai/install.ps1 | iex
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun
관련 링크
- 공식 원문: install/installer
- OpenClaw 문서 홈
이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.