OpenClaw 시작 매개변수 및 명령줄 옵션 대전

서문

OpenClaw의 명령줄 도구 openclaw은 AI 게이트웨이를 관리하는 주요 진입점입니다. 설정 파일 외에도, 많은 동작을 시작 매개변수로 임시 재정의하거나 조정할 수 있습니다. 이 글에서는 openclaw의 모든 하위 명령과 매개변수 옵션을 완전히 나열하여, 다양한 시나리오에서 유연하게 사용할 수 있도록 돕겠습니다.

전역 옵션

다음 옵션은 모든 하위 명령에 적용됩니다:

openclaw [전역 옵션] <하위 명령> [하위 명령 옵션]

옵션	축약	설명
`--config <path>`	`-c`	설정 파일 경로를 지정하여 기본 `~/.openclaw/openclaw.json`을 재정의합니다
`--log-level <level>`	`-l`	로그 레벨: `debug`, `info`, `warn`, `error`
`--quiet`	`-q`	조용한 모드, 오류 메시지만 출력합니다
`--verbose`	`-v`	상세 출력 모드, `--log-level debug`와 동일합니다
`--no-color`		터미널 컬러 출력을 비활성화합니다
`--version`	`-V`	버전 번호를 표시합니다
`--help`	`-h`	도움말 정보를 표시합니다

예제

# 커스텀 설정 파일로 시작
openclaw -c /etc/openclaw/production.json gateway

# 디버그 모드로 실행
openclaw -v gateway

# 버전 확인
openclaw --version

gateway 명령

gateway는 AI 게이트웨이 서비스를 시작하는 가장 핵심적인 명령입니다.

openclaw gateway [옵션]

옵션	축약	기본값	설명
`--port <number>`	`-p`	`18789`	게이트웨이 리스닝 포트
`--host <address>`	`-H`	`127.0.0.1`	리스닝 주소
`--daemon`	`-d`		데몬 프로세스 모드로 실행 (백그라운드 실행)
`--pid-file <path>`		`~/.openclaw/openclaw.pid`	PID 파일 경로
`--workers <number>`	`-w`	`0`(자동)	워커 스레드 수
`--timeout <ms>`	`-t`	`120000`	요청 타임아웃 (밀리초)
`--no-dashboard`			내장 Dashboard를 시작하지 않음
`--channels <list>`		전체	지정된 채널만 활성화, 쉼표로 구분
`--dry-run`			설정을 검증하고 시작을 시뮬레이션하지만 실제로 실행하지 않음

일반적인 사용법

# 기본 시작
openclaw gateway

# 포트와 주소 지정
openclaw gateway --port 8080 --host 0.0.0.0

# 백그라운드 실행
openclaw gateway --daemon

# Telegram과 Discord 채널만 활성화
openclaw gateway --channels telegram,discord

# 설정이 올바른지 검증 (실제 시작하지 않음)
openclaw gateway --dry-run

데몬 프로세스 관리

--daemon 모드로 시작한 후, 다음 명령으로 관리할 수 있습니다:

# 실행 상태 확인
openclaw status

# 정상적으로 중지
openclaw stop

# 강제 중지
openclaw stop --force

# 재시작
openclaw restart

# 핫 리로드 설정 (연결 중단 없이)
openclaw reload

dashboard 명령

게이트웨이 서비스 없이 Web Dashboard만 별도로 시작합니다.

openclaw dashboard [옵션]

옵션	축약	기본값	설명
`--port <number>`	`-p`	`18789`	Dashboard 포트
`--gateway <url>`	`-g`	`http://localhost:18789`	연결할 게이트웨이 주소
`--open`	`-o`		시작 후 자동으로 브라우저 열기
`--no-auth`			비밀번호 인증 건너뛰기 (개발 환경 전용)

예제

# 시작 후 브라우저 열기
openclaw dashboard --open

# 원격 게이트웨이에 연결
openclaw dashboard --gateway https://remote-server:18789

# 커스텀 포트 사용
openclaw dashboard --port 3000

doctor 명령

설정, 종속성 및 연결 상태를 검사하는 진단 도구입니다.

openclaw doctor [옵션]

옵션	설명
`--config-only`	설정 파일의 구문 및 필수 항목만 확인
`--connectivity`	설정된 모든 채널과 모델의 네트워크 연결성 테스트
`--remote`	외부 접근이 정상인지 테스트 (webhookBase 설정 필요)
`--fix`	수정 가능한 문제를 자동으로 수정 (예: 누락된 디렉토리 생성)

출력 예제

$ openclaw doctor

OpenClaw 진단 보고서
==================

설정 파일
  ✓ 설정 파일 형식 정상
  ✓ 모든 필수 항목 설정 완료

모델 연결
  ✓ Claude API 연결 정상 (지연시간: 230ms)
  ✓ OpenAI API 연결 정상 (지연시간: 180ms)
  ✗ Ollama 연결 실패: ECONNREFUSED localhost:11434

채널 상태
  ✓ Telegram Bot 인증 완료
  ✓ Discord Bot 로그인 완료
  - WhatsApp 미설정

시스템 환경
  ✓ Node.js v20.11.0
  ✓ 디스크 공간 충분 (사용 가능: 50GB)
  ✓ 메모리 충분 (사용 가능: 4.2GB)

문제: 1
  1. Ollama 서비스가 실행되지 않습니다. Ollama를 시작하거나 해당 모델 설정을 비활성화하세요

session 명령

대화 세션 데이터를 관리합니다.

openclaw session <하위 명령> [옵션]

하위 명령	설명
`list`	모든 세션 나열
`stats`	세션 통계 정보 조회
`clear`	세션 데이터 삭제
`export`	세션 내보내기
`compact`	수동으로 압축 트리거
`trim`	기록을 지정된 건수로 정리

자주 사용하는 작업

# 모든 활성 세션 나열
openclaw session list

# Agent별 필터링
openclaw session list --agent default

# 특정 세션의 상세 통계 조회
openclaw session stats --session telegram_123456

# 특정 세션 삭제
openclaw session clear --session telegram_123456

# 특정 Agent의 모든 세션 삭제
openclaw session clear --agent default --all

# 세션을 JSON으로 내보내기
openclaw session export --session telegram_123456 --format json

# 수동 압축
openclaw session compact --session telegram_123456

# 최근 20개 메시지만 유지
openclaw session trim --session telegram_123456 --keep 20

mobile 명령

모바일 기기 페어링을 관리합니다.

openclaw mobile <하위 명령> [옵션]

하위 명령	설명
`pair`	페어링 코드 또는 QR 코드 생성
`list`	페어링된 기기 나열
`remove`	기기 제거

예제

# 텍스트 페어링 코드 생성
openclaw mobile pair --generate

# QR 코드 생성
openclaw mobile pair --qrcode

# 기기 나열
openclaw mobile list

# 지정된 기기 제거
openclaw mobile remove mob_a3f2c1d8

# 모든 기기 제거
openclaw mobile remove --all

config 명령

설정을 조회하고 관리합니다.

openclaw config <하위 명령> [옵션]

하위 명령	설명
`--dump`	현재 적용 중인 전체 설정 출력
`--get <key>`	지정된 설정 항목의 값 조회
`--set <key> <value>`	설정 항목 설정
`--edit`	시스템 편집기로 설정 파일 열기
`--init`	기본 설정 파일 생성
`--validate`	설정 파일 검증

예제

# 전체 설정 조회
openclaw config --dump

# 특정 설정 값 조회
openclaw config --get gateway.port

# 설정 값 변경
openclaw config --set gateway.port 8080

# 기본 설정 초기화
openclaw config --init

# 편집기 열기
openclaw config --edit

access 명령

접근 제어 및 권한을 관리합니다.

openclaw access <하위 명령> [옵션]

하위 명령	설명
`allow <id>`	사용자 또는 그룹을 화이트리스트에 추가
`deny <id>`	사용자 또는 그룹을 블랙리스트에 추가
`remove <id>`	화이트리스트 또는 블랙리스트에서 제거
`list`	현재 화이트리스트와 블랙리스트 나열
`pair-code`	페어링 코드 생성
`log`	접근 로그 조회

예제

# 사용자를 화이트리스트에 추가
openclaw access allow tg:123456789

# 사용자 차단
openclaw access deny tg:999888777

# 화이트리스트 조회
openclaw access list

# 접근 로그 조회
openclaw access log --tail 50

media 명령

미디어 파일 캐시를 관리합니다.

openclaw media <하위 명령>

하위 명령	설명
`cleanup`	미디어 캐시 정리
`stats`	캐시 통계 조회

환경 변수

일부 시작 매개변수는 환경 변수로도 설정할 수 있으며, 환경 변수의 우선순위는 설정 파일보다 높지만 명령줄 매개변수보다 낮습니다:

환경 변수	대응 매개변수
`OPENCLAW_CONFIG`	`--config`
`OPENCLAW_PORT`	`--port`
`OPENCLAW_HOST`	`--host`
`OPENCLAW_LOG_LEVEL`	`--log-level`
`OPENCLAW_DASHBOARD_PASSWORD`	Dashboard 비밀번호
`OPENCLAW_CLAUDE_API_KEY`	Claude API 키
`OPENCLAW_OPENAI_API_KEY`	OpenAI API 키
`OPENCLAW_TELEGRAM_TOKEN`	Telegram Bot Token

우선순위 순서 (높은 것부터): 명령줄 매개변수 > 환경 변수 > 설정 파일 > 기본값

systemd 서비스 설정

Linux 서버에서는 systemd로 OpenClaw을 관리하는 것을 권장합니다:

# /etc/systemd/system/openclaw.service
[Unit]
Description=OpenClaw AI Gateway
After=network.target

[Service]
Type=simple
User=openclaw
WorkingDirectory=/home/openclaw
ExecStart=/usr/local/bin/openclaw gateway --port 18789 --host 0.0.0.0
ExecReload=/usr/local/bin/openclaw reload
Restart=always
RestartSec=5
Environment=OPENCLAW_CONFIG=/etc/openclaw/openclaw.json

[Install]
WantedBy=multi-user.target

sudo systemctl enable openclaw
sudo systemctl start openclaw
sudo systemctl status openclaw

정리

openclaw 명령줄 도구는 게이트웨이 시작부터 세션 관리까지, 문제 진단부터 권한 설정까지 완전한 기능 세트를 제공합니다. 일상적인 사용에서 gateway, doctor, session이 가장 자주 사용되는 세 가지 명령입니다. 명령줄 매개변수의 우선순위가 설정 파일보다 높다는 점을 기억하세요. 이를 통해 설정 파일을 수정하지 않고도 매개변수로 게이트웨이 동작을 임시 조정할 수 있어, 디버깅과 테스트에 매우 적합합니다.