Guide

Nylas 플러그인을 위한 OpenClaw CLI 설치

npm에서 OpenClaw를 설치하여 이메일, 캘린더, 연락처용 Nylas 플러그인을 사용하세요. PATH 수정, Windows 설정, 플러그인 설치 방법과 OpenClaw + Nylas가 모든 주요 이메일 프로바이더를 지원하는 과정을 다룹니다.

Written by Nick Barraclough Product Manager

Updated May 15, 2026

Verified — CLI 3.1.1 · Gmail, Outlook · last tested April 11, 2026

이 가이드에서 다루는 내용

OpenClaw는 AI 기반 메시징 어시스턴트를 구축하기 위한 오픈소스 CLI 프레임워크입니다. 이메일, WhatsApp, iMessage 및 기타 채널에 플러그인 시스템을 통해 연결하며, 현재 npm에 40개 이상의 커뮤니티 관리 패키지가 등록되어 있습니다. CLI를 npm에서 전역 설치하고, 필요한 통합을 위한 플러그인을 추가한 뒤, JSON 설정 파일로 각각을 구성합니다. 여기서의 목표는 OpenClaw를 설치하고 이메일, 캘린더, 연락처용 Nylas 플러그인을 실행할 준비를 하는 것입니다.

Nylas 사용자를 위한 빠른 설정

OpenClaw 안에서 Nylas를 실행하는 가장 빠른 방법은 Node.js가 이미 설치된 새 머신에서 3분 이내에 완료되는 7단계 순서입니다. CLI 설치, Nylas 플러그인 추가, 에이전트 세션 신뢰 설정, 이메일 계정에 대한 테스트 쿼리로 연결 확인까지 포함합니다.

아래 각 단계는 하나의 명령어를 실행합니다. config set 호출은 OpenClaw의 JSON 설정 파일(~/.openclaw/config.json)에 기록하며, gateway 재시작은 활성 세션을 유지하면서 변경 사항을 적용합니다.

아직 Nylas API 키가 없다면, 5단계 전에 Nylas 계정을 생성한 뒤 API 키를 OpenClaw 플러그인 설정에 복사하세요.

# 1. OpenClaw 설치
npm install -g openclaw

# 2. 바이너리가 PATH에 있는지 확인
openclaw --version

# 3. Nylas 플러그인 설치
openclaw plugins install @nylas/openclaw-nylas-plugin

# 4. 플러그인을 신뢰하고 에이전트 세션에 도구 노출
openclaw config set 'plugins.allow' '["nylas"]'
openclaw config set 'tools.alsoAllow' '["nylas"]'

# 5. Nylas API 키 설정
openclaw config set 'plugins.entries.nylas.config.apiKey' 'YOUR_NYLAS_API_KEY'

# 6. 플러그인 설정이 다시 로드되도록 gateway 재시작
openclaw gateway restart

# 7. 통합 확인
openclaw plugins list
openclaw run "List my connected email accounts" --plugin nylas

이어지는 섹션에서는 각 설치 단계를 자세히 설명하고, 일반적인 환경에 대한 PATH 수정을 다루며, macOS/Linux와 Windows 모두에 대한 문제 해결을 안내합니다.

OpenClaw npm 패키지 이름은 무엇인가요?

OpenClaw CLI는 스코프 없는 패키지 이름 openclaw로 npm에 게시되어 있습니다. 코어 CLI 바이너리에는 @openclaw/ 스코프 접두사가 없습니다. 플러그인은 @nylas/openclaw-nylas-plugin처럼 스코프가 지정된 이름을 사용하지만, CLI 자체는 최상위 openclaw 패키지에서 설치됩니다. 이 패키지는 2025년 초부터 npm에 있으며 2026년 5월 기준 주간 다운로드 수가 12,000회를 넘습니다.

npm install -g openclaw을 실행하면 openclaw 바이너리가 npm 전역 bin 디렉터리(일반적으로 $(npm config get prefix)/bin/)에 배치됩니다.

# npm 패키지 이름은 "openclaw"
npm install -g openclaw

OpenClaw CLI 설치

OpenClaw CLI 설치에는 Node.js 22.12.0 이상과 하나의 npm install -g 명령어가 필요합니다. 전역 설치는 openclaw 바이너리를 시스템 PATH에 배치하여 모든 터미널 세션에서 사용할 수 있게 합니다. 일반적인 광대역 연결에서 전체 설치는 60초 이내에 완료되며 약 45 MB의 종속성을 다운로드합니다.

먼저 Node.js 버전을 확인하세요. OpenClaw는 네이티브 ES 모듈과 Node.js 내장 테스트 러너를 사용하며, 둘 다 최소 Node.js 22.12.0이 필요합니다. 이전 버전은 시작 시 구문 오류로 실패합니다.

# Node.js 버전 확인 (22.12.0 이상이어야 함)
node --version

# OpenClaw CLI 전역 설치
npm install -g openclaw

# 설치 확인
openclaw --version

버전 번호가 표시되면 설치가 성공한 것입니다. "command not found" 오류는 npm 전역 bin 디렉터리가 PATH에 포함되지 않았다는 의미입니다 — PATH 수정에 대한 문제 해결 섹션에서 직접 다룹니다.

nvm으로 Node.js를 관리하는 시스템에서는 설치 전에 활성 Node 버전이 22.12.0 이상인지 확인하세요:

# nvm으로 Node.js 22로 전환
nvm install 22
nvm use 22

# 그런 다음 openclaw 설치
npm install -g openclaw

시스템 요구 사항은 무엇인가요?

OpenClaw는 macOS(Intel 및 Apple Silicon), Linux(x64 및 arm64), Windows 10 이상에서 실행됩니다. 유일한 필수 종속성은 Node.js 22.12.0+이며, 약 80 MB의 디스크 공간이 필요합니다. OpenClaw는 자체 종속성으로 약 45 MB를 추가합니다. CLI가 네이티브 애드온 없는 순수 JavaScript이므로 네이티브 컴파일러 툴체인이 필요하지 않습니다.

플랫폼	Node.js 설치	참고
macOS	`brew install node@22`	Apple Silicon과 Intel 모두 지원
Ubuntu / Debian	NodeSource 또는 `nvm`	시스템 apt 패키지는 너무 오래됨
Windows	nodejs.org 설치 프로그램	cmd.exe 대신 PowerShell 사용
WSL	`nvm`	Linux 안내와 동일

OpenClaw 플러그인 설치

OpenClaw 플러그인은 CLI에 새로운 도구, 통합, 명령어를 등록하는 npm 패키지입니다. 내장 플러그인 관리자가 다운로드, 버전 해석, 도구 등록을 처리합니다. 2026년 5월 기준 OpenClaw 생태계에는 이메일, 메시징, CRM, 개발자 도구를 다루는 40개 이상의 플러그인이 게시되어 있습니다. 각 플러그인은 몇 초 내에 설치되며 gateway 재시작 후 활성화됩니다.

openclaw plugins 하위 명령어는 전체 플러그인 수명주기를 관리합니다: 설치, 목록, 업데이트, 제거. 플러그인을 설치하거나 플러그인 설정을 변경한 후에는 openclaw gateway restart를 실행하여 gateway 프로세스가 새 플러그인 상태를 로드하도록 하세요.

# 플러그인 설치
openclaw plugins install <package-name>

# 예: 이메일, 캘린더, 연락처용 Nylas 플러그인 설치
openclaw plugins install @nylas/openclaw-nylas-plugin

# 설치 확인
openclaw plugins list

# 새 플러그인이 로드되도록 gateway 재시작
openclaw gateway restart

플러그인 관리 명령어 참조

명령어	설명
`openclaw plugins install <pkg>`	npm에서 플러그인 설치
`openclaw plugins uninstall <pkg>`	설치된 플러그인 제거
`openclaw plugins list`	설치된 모든 플러그인 목록 보기
`openclaw plugins list --json`	플러그인 목록을 JSON 형식으로 보기
`openclaw plugins update <pkg>`	플러그인을 최신 버전으로 업데이트
`openclaw plugins update --all`	설치된 모든 플러그인 업데이트

설치된 플러그인 목록 보기

openclaw plugins list 명령어는 설치된 모든 플러그인의 버전 번호와 활성/비활성 상태를 출력합니다. 출력은 NAME, VERSION, STATUS의 3열 테이블입니다. --json 플래그를 추가하면 jq로 파이프하거나 스크립트에서 파싱할 수 있는 머신 판독 가능한 JSON을 생성합니다 — 에이전트 배포 전 필수 플러그인 세트를 확인하는 CI 검사에 유용합니다.

플러그인이 "active"로 표시되면 도구가 로드되어 에이전트 세션에서 사용할 수 있다는 뜻입니다. "inactive" 상태는 플러그인이 설치되었지만 설정에서 비활성화되었거나 마지막 gateway 시작 시 초기화에 실패했다는 의미입니다.

# 설치된 모든 플러그인 목록 보기
openclaw plugins list

# 출력 예시:
# NAME                              VERSION  STATUS
# @nylas/openclaw-nylas-plugin      1.2.0    active
# openclaw-whatsapp-bridge          0.9.1    active
# openclaw-imsg                     0.8.3    active

# 스크립팅용 JSON 출력
openclaw plugins list --json

플러그인 제거

openclaw plugins uninstall 명령어는 플러그인을 제거하고 CLI에서 모든 도구의 등록을 한 번에 해제합니다. 설치와 달리 gateway 재시작 없이 즉시 적용됩니다. 플러그인의 npm 패키지는 로컬 ~/.openclaw/plugins/디렉터리에서 삭제되어 종속성에 따라 일반적으로 5-15 MB의 디스크 공간이 해제됩니다.

설치 시 사용했던 전체 npm 패키지 이름을 정확히 전달하세요. 이후 openclaw plugins list를 실행하여 플러그인이 더 이상 표시되지 않는지 확인하세요.

# 플러그인 제거
openclaw plugins uninstall @nylas/openclaw-nylas-plugin

# 제거 확인
openclaw plugins list

Windows에서 OpenClaw 설정

OpenClaw는 PowerShell 5.1+ 이상의 Windows 10 이상에서 기본적으로 실행됩니다. Windows 설치 경로는 macOS 및 Linux와 동일합니다: Node.js 22.12.0 이상을 설치한 다음 npm install -g openclaw을 실행합니다. Node.js Foundation에 따르면, nodejs.org의 Windows .msi 설치 프로그램은 자동으로 Node.js와 npm을 시스템 PATH에 추가하므로, 대부분의 경우 수동 PATH 편집 없이 OpenClaw 바이너리를 사용할 수 있습니다.

# Windows PowerShell 설정
# 1. https://nodejs.org에서 Node.js 22+ 설치 (LTS 설치 프로그램 사용)

# 2. PowerShell을 열고 Node.js 확인
node --version

# 3. OpenClaw 전역 설치
npm install -g openclaw

# 4. 확인
openclaw --version

# 5. EACCES 또는 권한 오류가 발생하면, 관리자 권한으로 PowerShell 실행:
# PowerShell 우클릭 → "관리자 권한으로 실행"
# 그런 다음 반복: npm install -g openclaw

Windows에서 OpenClaw 설정 디렉터리는 %USERPROFILE%\.openclaw\입니다. 플러그인과 설정 파일이 이 디렉터리에 저장됩니다. PATH에 npm 전역 bin 디렉터리가 포함되어 있는지 확인하세요. Node.js 설치 프로그램이 일반적으로 자동으로 설정합니다.

선택 사항: iMessage CLI 경로 설정

openclaw-imsg 플러그인은 macOS에서 OpenClaw를 iMessage에 연결합니다. macOS 앱 샌드박싱이 바이너리 위치를 제한하기 때문에, 플러그인이 iMessage CLI 바이너리를 자동 감지할 수 없습니다 — openclaw config set imsg.cliPath를 통해 경로를 명시적으로 설정해야 합니다. 이 추가 단계는 약 30초 소요되며 머신당 한 번만 필요합니다.

iMessage CLI 바이너리(imsg-cli)는 별도의 오픈소스 도구입니다. Homebrew로 설치한 경우 바이너리는 $(brew --prefix)/bin/ 아래에 있습니다. 수동 설치는 일반적으로 /usr/local/bin/imsg-cli에 배치합니다.

# iMessage 플러그인 설치
openclaw plugins install openclaw-imsg

# iMessage CLI 바이너리 경로 설정
openclaw config set imsg.cliPath "/usr/local/bin/imsg-cli"

# Homebrew로 imsg-cli를 설치한 경우:
openclaw config set imsg.cliPath "$(brew --prefix)/bin/imsg-cli"

# 경로가 설정되었는지 확인
openclaw config get imsg.cliPath

# iMessage 연결 테스트
openclaw imsg status

imsg.cliPath 설정 값은 실제 바이너리를 가리켜야 합니다. 플러그인에서 "command not found" 오류가 발생하면 경로가 잘못되었거나 해당 위치에 바이너리가 존재하지 않는 것입니다. which imsg-cli를 사용하여 시스템의 올바른 경로를 찾으세요.

선택 사항: WhatsApp 통합

openclaw-whatsapp-bridge 플러그인은 OpenClaw를 WhatsApp Business API에 연결합니다. Meta의 2025년 실적 보고서에 따르면 WhatsApp은 월간 활성 사용자 20억 명 이상을 보유하고 있습니다. 이 플러그인은 Meta의 Cloud API를 통해 메시지 전송, 수신, 웹훅 등록을 처리합니다. WhatsApp Business 계정과 Meta 개발자 대시보드의 액세스 토큰이 필요합니다. 자격 증명이 준비되면 설정에 약 5분이 소요됩니다.

3가지 설정 값이 필요합니다: 액세스 토큰, 전화번호 ID, 비즈니스 계정 ID. 세 가지 모두 Meta Developer Portal의 WhatsApp 앱 설정에서 확인할 수 있습니다.

# WhatsApp bridge 플러그인 설치
openclaw plugins install openclaw-whatsapp-bridge

# WhatsApp Business 자격 증명 설정
openclaw config set whatsapp.accessToken "YOUR_ACCESS_TOKEN"
openclaw config set whatsapp.phoneNumberId "YOUR_PHONE_NUMBER_ID"
openclaw config set whatsapp.businessAccountId "YOUR_BUSINESS_ACCOUNT_ID"

# 설정 확인
openclaw whatsapp status

# 테스트 메시지 전송
openclaw whatsapp send --to "+1234567890" --message "Hello from OpenClaw"

전화번호 ID는 에이전트를 대신하여 메시지를 보내는 WhatsApp 번호를 식별합니다. Meta Developer Portal에서 생성된 액세스 토큰은 Business Settings의 System Users 페이지에서 영구 토큰을 생성하지 않으면 24시간 후 만료됩니다. 프로덕션 배포에서는 인증 실패를 방지하기 위해 영구 토큰을 사용하세요.

선택 사항: exec-approvals.json 설정

OpenClaw의 exec 승인 시스템은 플러그인이 머신에서 실행할 수 있는 셸 명령어를 제어합니다. exec-approvals.json 파일은 3가지 동작의 패턴 기반 규칙을 정의합니다: allow, deny, 또는 ask(실행 전 확인). 이 파일이 없으면 OpenClaw는 기본적으로 모든 셸 명령어에 대해 확인을 요청하므로, 명시적으로 승인하지 않는 한 플러그인이 아무것도 자동으로 실행할 수 없습니다.

설정 파일은 macOS와 Linux에서 ~/.openclaw/exec-approvals.json, Windows에서 %USERPROFILE%\.openclaw\exec-approvals.json에 있습니다. 규칙은 위에서 아래로 평가되며, 첫 번째로 매칭되는 패턴이 적용됩니다. 아래 예시는 Nylas CLI, curl, 파일 삭제를 다루는 3개 규칙의 일반적인 설정을 보여줍니다.

// Example exec-approvals.json
{
  "version": 1,
  "rules": [
    {
      "pattern": "nylas *",
      "action": "allow",
      "comment": "Allow all Nylas CLI commands"
    },
    {
      "pattern": "curl *",
      "action": "ask",
      "comment": "Prompt before running curl"
    },
    {
      "pattern": "rm *",
      "action": "deny",
      "comment": "Never allow file deletion"
    }
  ],
  "default": "ask"
}

default 필드는 일치하는 규칙이 없을 때의 동작을 제어합니다. 알 수 없는 명령어에 대해 확인을 받으려면 "ask", 명시적으로 허용되지 않은 모든 것을 차단하려면 "deny", 모든 플러그인을 완전히 신뢰하면 "allow"로 설정하세요. 대부분의 사용자에게 "ask"가 가장 안전한 기본값입니다.

cat으로 현재 설정을 확인하거나 OpenClaw 기본값으로 초기화할 수 있습니다. 초기화 명령어는 기본 동작이 ask이고 사용자 정의 규칙이 없는 초기 exec-approvals.json을 복원합니다.

# 현재 exec 승인 설정 보기
cat ~/.openclaw/exec-approvals.json

# 기본값으로 초기화
openclaw config reset exec-approvals

Nylas 플러그인 추가

@nylas/openclaw-nylas-plugin은 OpenClaw에 네이티브 이메일, 캘린더, 연락처 도구를 추가합니다. Nylas 플러그인은 단일 API를 통해 6개 이메일 프로바이더 — Gmail, Outlook, Exchange, Yahoo, iCloud, IMAP — 를 지원합니다. 메시지 CRUD, 캘린더 이벤트 관리, 연락처 검색, 첨부 파일 처리를 다루는 20개 이상의 도구를 OpenClaw에 등록합니다.

설치에는 npm 패키지 이름, Nylas API 키(dashboard.nylas.com에서 발급), gateway 재시작이 필요합니다. API 키는 OpenClaw의 로컬 설정 파일에 저장되며 머신 밖으로 전송되지 않습니다.

# Nylas 플러그인 설치
openclaw plugins install @nylas/openclaw-nylas-plugin

# Nylas API 키 설정
openclaw config set 'plugins.entries.nylas.config.apiKey' 'YOUR_NYLAS_API_KEY'

# 플러그인 설정이 다시 로드되도록 gateway 재시작
openclaw gateway restart

# 플러그인이 연결된 계정을 볼 수 있는지 확인
openclaw run "List my connected email accounts" --plugin nylas

다중 계정 설정, 전체 도구 참조 테이블, 프로바이더별 문제 해결에 대해서는 OpenClaw Nylas 플러그인 설치 가이드를 참조하세요.

문제 해결: npm install -g 후 "command not found"

npm install -g openclaw 후 "command not found" 오류는 npm 전역 bin 디렉터리가 셸의 PATH에 포함되지 않았다는 의미입니다. 이것은 가장 흔한 설치 후 문제이며, nvm이나 수동 tarball로 Node.js를 설치한 Linux 및 macOS 사용자 5명 중 약 1명에게 영향을 미칩니다. 해결 방법은 npm prefix 디렉터리를 찾아 해당 bin/ 하위 디렉터리를 셸 프로필에 추가하는 것입니다.

npm config get prefix를 실행하여 디렉터리를 확인하세요. 기본 nvm 설치에서 prefix는 일반적으로 ~/.nvm/versions/node/v22.x.x입니다. openclaw 바이너리는 <prefix>/bin/openclaw에 있습니다.

# npm이 전역 바이너리를 설치하는 위치 확인
npm config get prefix

# 바이너리는 <prefix>/bin/openclaw에 있음
# bin 디렉터리를 PATH에 추가

# bash (~/.bashrc)의 경우:
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# zsh (~/.zshrc)의 경우:
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 작동 확인
openclaw --version

nvm을 사용하면 Node 버전을 전환할 때 전역 prefix가 변경됩니다. 일상적으로 사용하는 Node 버전에서 OpenClaw를 설치하세요. nvm use 22 && npm install -g openclaw을 실행하면 Node 22가 활성화될 때마다 바이너리를 사용할 수 있습니다.

문제 해결: 플러그인 설치 실패

openclaw plugins install의 플러그인 설치 실패는 3가지로 분류됩니다: npm 버전 불일치, 네트워크/프록시 오류, 파일 권한 오류. 가장 흔한 원인은 OpenClaw 플러그인이 의존하는 종속성 해석 기능이 없는 npm 9 이하를 사용하는 것입니다. npm 10+는 기본적으로 Node.js 22와 함께 제공됩니다. 아래 단계는 각 실패 유형을 가능성 순서대로 다룹니다.

먼저 Node.js와 npm 버전을 확인하세요. 둘 다 최신이면 npm 캐시를 지우고 재시도하세요. 기업 프록시와 파일 소유권 문제는 덜 흔하지만 OpenClaw GitHub 이슈 트래커에 보고된 설치 실패의 약 15%를 차지합니다.

# 1. Node.js와 npm 버전 확인
node --version   # 22.12.0 이상이어야 함
npm --version    # 10 이상이어야 함

# 2. npm 캐시 지우기
npm cache clean --force

# 3. 다시 설치 시도
openclaw plugins install @nylas/openclaw-nylas-plugin

# 4. 기업 프록시 뒤에 있다면, npm 설정
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# 5. macOS/Linux에서 권한 오류 시, npm prefix 소유권 수정
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

문제 해결: 플러그인이 설치되었지만 로드되지 않음

openclaw plugins list에서 플러그인이 "active"로 표시되지만 에이전트 세션 중 도구나 명령어를 사용할 수 없을 때, 플러그인이 시작 시 초기화에 실패했을 가능성이 있습니다. 플러그인의 필수 설정 값이 누락되었거나 종속성 충돌로 플러그인의 진입점이 로드되지 않을 때 발생할 수 있습니다. --debug플래그는 실패한 플러그인의 정확한 오류 메시지를 포함한 상세 초기화 로그를 stderr에 출력합니다.

플러그인을 재설치하면 새로 다운로드하고 OpenClaw에 도구를 다시 등록합니다. 제거 후 설치 과정은 대부분의 연결에서 10초 이내에 완료됩니다.

# 플러그인 오류에 대한 디버그 로그 확인
openclaw --debug 2>&1 | grep -i plugin

# 문제가 있는 플러그인 재설치
openclaw plugins uninstall <package-name>
openclaw plugins install <package-name>

# 올바르게 로드되는지 확인
openclaw plugins list

다음 단계

OpenClaw가 설치되고 Nylas 플러그인이 등록되면, CLI는 이메일, 캘린더, 연락처 자동화를 위한 준비가 완료됩니다. 아래 가이드에서는 플러그인 설정을 상세히 다루고, 에이전트 구축 패턴과 가장 흔한 OpenClaw 문제의 오류 해결을 안내합니다.

OpenClaw Nylas 플러그인 설치 — 타입 스키마와 자동 검색을 갖춘 이메일, 캘린더, 연락처 도구 추가
Nylas CLI와 OpenClaw로 개인 어시스턴트 만들기 — 셸 명령어를 직접 사용하는 exec 기반 접근 방식
OpenClaw 이메일 접근 보안 — 플러그인 허용 목록, 자격 증명, 정책, 전송 승인 잠금
이메일 및 캘린더용 AI Agent CLI — 커스텀 에이전트를 위한 서브프로세스 기반 이메일 및 캘린더 도구 구축
OpenClaw CLI 오류 해결 — PATH, npm 권한, Node.js 버전, Windows 설정 문제 해결
Nylas CLI 명령어 참조 — 모든 명령어, 플래그, 옵션의 전체 참조