Setup

Setup 문서는 OpenClaw 공식 문서(start/setup)를 한국어로 정리한 가이드입니다. Advanced setup and development workflows for OpenClaw 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Advanced setup and development workflows for OpenClaw

한국어 가이드 범위: start/setup 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

TL;DR
Prereqs (from source)
Tailoring strategy (so updates do not hurt)
Run the Gateway from this repo
Stable workflow (macOS app first)
Bleeding edge workflow (Gateway in a terminal)
0) (Optional) Run the macOS app from source too
1) Start the dev Gateway
First run only (or after resetting local OpenClaw config/workspace)
2) Point the macOS app at your running Gateway
3) Verify
Common footguns
Credential storage map
Updating (without wrecking your setup)
Linux (systemd user service)
Related docs

상세 내용

본문

If you are setting up for the first time, start with Getting Started. For onboarding details, see Onboarding (CLI).

TL;DR

Pick a setup workflow based on how often you want updates and whether you want to run the Gateway yourself:

주요 항목:

Tailoring lives outside the repo: keep your config and workspace in ~/.openclaw/openclaw.json and ~/.openclaw/workspace/ so repo updates don't touch them.
Stable workflow (recommended for most): install the macOS app and let it run the bundled Gateway.
Bleeding edge workflow (dev): run the Gateway yourself via pnpm gateway:watch, then let the macOS app attach in Local mode.

Prereqs (from source)

extensions/* pnpm workspace packages in dev mode, so root npm install does not prepare the full source tree.

주요 항목:

Node 24.15+ recommended (Node 22 LTS, currently 22.22.3+, still supported)
pnpm required for source checkouts. OpenClaw loads bundled plugins from the
Docker (optional; only for containerized setup/e2e - see Docker)

Tailoring strategy (so updates do not hurt)

If you want "100% tailored to me" and easy updates, keep your customization in:

주요 항목:

Config: ~/.openclaw/openclaw.json (JSON/JSON5-ish)
Workspace: ~/.openclaw/workspace (skills, prompts, memories; make it a private git repo)

openclaw setup --baseline

pnpm openclaw setup --baseline

Run the Gateway from this repo

After pnpm build, you can run the packaged CLI directly:

node openclaw.mjs gateway --port 18789 --verbose

Stable workflow (macOS app first)

Install + launch OpenClaw.app (menu bar). 2. Complete the onboarding/permissions checklist (TCC prompts). 3. Ensure Gateway is Local and running (the app manages it). 4. Link surfaces (example: WhatsApp):

주요 항목:

Run openclaw setup, then openclaw channels login, then start the Gateway manually (openclaw gateway).

openclaw channels login

openclaw health

Bleeding edge workflow (Gateway in a terminal)

Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.

0) (Optional) Run the macOS app from source too

If you also want the macOS app on the bleeding edge:

./scripts/restart-mac.sh

1) Start the dev Gateway

pnpm install

### First run only (or after resetting local OpenClaw config/workspace)

pnpm openclaw setup pnpm gateway:watch ```

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

### 2) Point the macOS app at your running Gateway

The app will attach to the running gateway on the configured port.

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

주요 항목:

- Connection Mode: **Local**

### 3) Verify

주요 항목:

- In-app Gateway status should read **"Using existing gateway …"**
- Or via CLI:

```bash
openclaw health

Common footguns

주요 항목:

Wrong port: Gateway WS defaults to ws://127.0.0.1:18789; keep app + CLI on the same port.
Where state lives:
Channel/provider state: ~/.openclaw/credentials/
Model auth profiles: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
Sessions and transcripts: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
Legacy/archive session artifacts: ~/.openclaw/agents/<agentId>/sessions/
Logs: /tmp/openclaw/

Credential storage map

Use this when debugging auth or deciding what to back up:

주요 항목:

WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
Telegram bot token: config/env or channels.telegram.tokenFile (regular file only; symlinks rejected)
Discord bot token: config/env or SecretRef (env/file/exec providers)
Slack tokens: config/env (channels.slack.*)
Pairing allowlists:
~/.openclaw/credentials/<channel>-allowFrom.json (default account)
~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (non-default accounts)
Model auth profiles: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
File-backed secrets payload (optional): ~/.openclaw/secrets.json
Legacy OAuth import: ~/.openclaw/credentials/oauth.json

Updating (without wrecking your setup)

주요 항목:

Keep ~/.openclaw/workspace and ~/.openclaw/ as "your stuff"; don't put personal prompts/config into the openclaw repo.
Updating source: git pull + pnpm install + keep using pnpm gateway:watch.

Linux (systemd user service)

Linux installs use a systemd user service. By default, systemd stops user services on logout/idle, which kills the Gateway. Onboarding attempts to enable lingering for you (may prompt for sudo). If it's still off, run:

sudo loginctl enable-linger $USER

주요 항목:

Gateway runbook (flags, supervision, ports)
Gateway configuration (config schema + examples)
Discord and Telegram (reply tags + replyToMode settings)
OpenClaw assistant setup
macOS app (gateway lifecycle)

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/start/setup
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw setup --baseline

pnpm openclaw setup --baseline

node openclaw.mjs gateway --port 18789 --verbose

openclaw channels login

openclaw health

./scripts/restart-mac.sh

Setup

핵심 요약

Advanced setup and development workflows for OpenClaw

한국어 가이드 범위: start/setup 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

TL;DR
Prereqs (from source)
Tailoring strategy (so updates do not hurt)
Run the Gateway from this repo
Stable workflow (macOS app first)
Bleeding edge workflow (Gateway in a terminal)
0) (Optional) Run the macOS app from source too
1) Start the dev Gateway
First run only (or after resetting local OpenClaw config/workspace)
2) Point the macOS app at your running Gateway
3) Verify
Common footguns
Credential storage map
Updating (without wrecking your setup)
Linux (systemd user service)
Related docs

상세 내용

본문

If you are setting up for the first time, start with Getting Started. For onboarding details, see Onboarding (CLI).

TL;DR

Pick a setup workflow based on how often you want updates and whether you want to run the Gateway yourself:

주요 항목:

Tailoring lives outside the repo: keep your config and workspace in ~/.openclaw/openclaw.json and ~/.openclaw/workspace/ so repo updates don't touch them.
Stable workflow (recommended for most): install the macOS app and let it run the bundled Gateway.
Bleeding edge workflow (dev): run the Gateway yourself via pnpm gateway:watch, then let the macOS app attach in Local mode.

Prereqs (from source)

extensions/* pnpm workspace packages in dev mode, so root npm install does not prepare the full source tree.

주요 항목:

Node 24.15+ recommended (Node 22 LTS, currently 22.22.3+, still supported)
pnpm required for source checkouts. OpenClaw loads bundled plugins from the
Docker (optional; only for containerized setup/e2e - see Docker)

Tailoring strategy (so updates do not hurt)

If you want "100% tailored to me" and easy updates, keep your customization in:

주요 항목:

Config: ~/.openclaw/openclaw.json (JSON/JSON5-ish)
Workspace: ~/.openclaw/workspace (skills, prompts, memories; make it a private git repo)

openclaw setup --baseline

pnpm openclaw setup --baseline

Run the Gateway from this repo

After pnpm build, you can run the packaged CLI directly:

node openclaw.mjs gateway --port 18789 --verbose

Stable workflow (macOS app first)

Install + launch OpenClaw.app (menu bar). 2. Complete the onboarding/permissions checklist (TCC prompts). 3. Ensure Gateway is Local and running (the app manages it). 4. Link surfaces (example: WhatsApp):

주요 항목:

Run openclaw setup, then openclaw channels login, then start the Gateway manually (openclaw gateway).

openclaw channels login

openclaw health

Bleeding edge workflow (Gateway in a terminal)

Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.

0) (Optional) Run the macOS app from source too

If you also want the macOS app on the bleeding edge:

./scripts/restart-mac.sh

1) Start the dev Gateway

pnpm install

### First run only (or after resetting local OpenClaw config/workspace)

pnpm openclaw setup pnpm gateway:watch ```

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

### 2) Point the macOS app at your running Gateway

The app will attach to the running gateway on the configured port.

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

주요 항목:

- Connection Mode: **Local**

### 3) Verify

주요 항목:

- In-app Gateway status should read **"Using existing gateway …"**
- Or via CLI:

```bash
openclaw health

Common footguns

주요 항목:

Wrong port: Gateway WS defaults to ws://127.0.0.1:18789; keep app + CLI on the same port.
Where state lives:
Channel/provider state: ~/.openclaw/credentials/
Model auth profiles: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
Sessions and transcripts: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
Legacy/archive session artifacts: ~/.openclaw/agents/<agentId>/sessions/
Logs: /tmp/openclaw/

Credential storage map

Use this when debugging auth or deciding what to back up:

주요 항목:

WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
Telegram bot token: config/env or channels.telegram.tokenFile (regular file only; symlinks rejected)
Discord bot token: config/env or SecretRef (env/file/exec providers)
Slack tokens: config/env (channels.slack.*)
Pairing allowlists:
~/.openclaw/credentials/<channel>-allowFrom.json (default account)
~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (non-default accounts)
Model auth profiles: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
File-backed secrets payload (optional): ~/.openclaw/secrets.json
Legacy OAuth import: ~/.openclaw/credentials/oauth.json

Updating (without wrecking your setup)

주요 항목:

Keep ~/.openclaw/workspace and ~/.openclaw/ as "your stuff"; don't put personal prompts/config into the openclaw repo.
Updating source: git pull + pnpm install + keep using pnpm gateway:watch.

Linux (systemd user service)

sudo loginctl enable-linger $USER

주요 항목:

Gateway runbook (flags, supervision, ports)
Gateway configuration (config schema + examples)
Discord and Telegram (reply tags + replyToMode settings)
OpenClaw assistant setup
macOS app (gateway lifecycle)

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/start/setup
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw setup --baseline

pnpm openclaw setup --baseline

node openclaw.mjs gateway --port 18789 --verbose

openclaw channels login

openclaw health

./scripts/restart-mac.sh

Setup

핵심 요약

문서 구성

상세 내용

본문

TL;DR

Prereqs (from source)

Tailoring strategy (so updates do not hurt)

Run the Gateway from this repo

Stable workflow (macOS app first)

Bleeding edge workflow (Gateway in a terminal)

0) (Optional) Run the macOS app from source too

1) Start the dev Gateway

Common footguns

Credential storage map

Updating (without wrecking your setup)

Linux (systemd user service)

Related docs

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Setup

핵심 요약

문서 구성

상세 내용

본문

TL;DR

Prereqs (from source)

Tailoring strategy (so updates do not hurt)

Run the Gateway from this repo

Stable workflow (macOS app first)

Bleeding edge workflow (Gateway in a terminal)

0) (Optional) Run the macOS app from source too

1) Start the dev Gateway

Common footguns

Credential storage map

Updating (without wrecking your setup)

Linux (systemd user service)

Related docs

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드