Meta Ads CLI 설정 방법: 2026년을 위한 단계별 튜토리얼

Meta Ads CLI를 설정하려면, Business Manager에서 System User를 만들고, ads_management, ads_read, business_management 권한이 있는 영구 만료되지 않는 토큰을 생성하며, Ad Account와 Page를 자산으로 연결한 다음, config 파일을 통해 CLI가 해당 토큰을 가리키도록 합니다. Business Manager의 admin 액세스, Facebook Page, Ad Account에서 인증된 결제 수단이 있다면 전체 과정에 약 45분이 걸립니다.

이 글은 AI 에이전트로 Facebook Ads 운영하기에 대한 개요의 심층 동반 가이드입니다. 그 글은 캠페인을 몇 개 이상 운영하는 사람에게 왜 CLI 기반 설정이 Ads Manager 클릭보다 나은지 설명합니다. 이 글은 실전 가이드입니다 — 모든 단계, 우리가 자체 스택을 구축할 때 마주친 모든 오류 메시지, 그리고 마지막에 실제 첫 캠페인 워크스루까지 포함되어 있습니다.

Meta Ads CLI가 실제로 하는 일

"Meta Ads CLI"는 단일 공식 바이너리가 아닙니다. 스크립트와 Meta Marketing API 사이에 자리잡은 얇은 서버 측 자동화 레이어입니다. Python이나 Node 코드를 작성하면, CLI가 인증, 요청 서명, 장기 유효 System User 토큰을 처리하며, 캠페인은 누구도 Ads Manager를 클릭하지 않고 graph.facebook.com/v23.0/을 통해 게시됩니다.

어려운 부분은 wrapper 코드가 아닙니다 — 그건 백 줄 정도입니다. 어려운 부분은 Business Manager 내부의 7단계 설정 의식인데, 이를 통해 Meta가 실제로 프로덕션 트래픽에 수락하는 토큰이 만들어집니다. 이 의식은 모든 브라우저 기반 자동화를 결국에는 망가뜨리는 OAuth 새로고침 댄스와 토큰 만료 고통을 제거합니다.

보상은 진짜입니다. CLI 스택이 실행되면, 90초 안에 6개의 광고 변형으로 캠페인을 시작하고, 매일 오전 7시 cron으로 어제 성과를 일일 리포트로 가져오며, 성과가 부진한 광고를 자동으로 일시정지할 수 있습니다 — Ads Manager에 한 번도 로그인하지 않고 말입니다.

사전 준비사항

시작하기 전에 다음 사항을 갖추고 있는지 확인합니다. 어느 하나라도 건너뛰면 나중에 2시간 동안 토끼굴로 빠지게 됩니다.

admin 권한이 있는 Meta Business Manager 계정이 필요합니다 — 개인 Facebook 계정은 System User 토큰에 작동하지 않습니다. 편집자가 아닌 admin으로 등록되어 있는 Facebook Page가 필요합니다. 해당 Business Manager 내부에 인증된 결제 수단과 결제 승인을 받은 국가가 최소 하나 있는 Meta Ad Account가 필요합니다. 트래픽을 유도하는 웹사이트에 대해 구성된 Pixel(또는 새로운 용어로 "Dataset")이 필요합니다. 그리고 패키지를 설치할 수 있는 Python 3.10+ 또는 Node 18+가 로컬에 설치되어 있어야 합니다.

Pixel이 아직 없다면, 계속하기 전에 만듭니다. 우리처럼 Conversions API (CAPI)만 사용할 계획이더라도 — 서버 측 이벤트의 라우팅 주소로 Pixel ID가 여전히 필요합니다.

7단계 설정

이 단계들은 순차적입니다. 각 단계가 다음 단계를 잠금 해제합니다. 앞서 건너뛰면 디버그하기 어려운 방식으로 체인이 끊어집니다. Meta의 오류 메시지가 종종 오해를 일으키기 때문입니다.

1단계: Business Manager System User 만들기

Business Settings → Users → System Users로 이동합니다. "Add"를 클릭하고 새 System User를 만듭니다. 이름은 API에는 중요하지 않지만 미래의 본인 정신 건강을 위해 중요합니다 — your-brand-agent 같은 이름으로 짓는 것이 좋습니다. 그래야 6개월 후에도 그것이 무엇을 하는지 기억할 수 있습니다. Role은 "Admin"(Employee가 아닌)을 선택합니다. admin 권한이 없는 System User는 Custom Conversions나 Pixel 이벤트를 관리할 수 없기 때문입니다.

우리가 스택을 구축할 때 emaxstudioagent를 만들었습니다. System User ID는 자동으로 할당됩니다(15자리 숫자). 적어둡니다.

2단계: Marketing API Use Case로 Developer App 만들기

developers.facebook.com → My Apps → Create App으로 이동합니다. 드롭다운에 "Marketing API"가 보이면 해당 use case를 선택합니다. "Other"만 보여도 괜찮습니다 — System User 토큰은 어느 쪽이든 작동합니다. 독일어 UI는 이것을 "Werbeanzeigen mit Marketing API"로 라벨링하고 영어 UI는 그냥 "Marketing API" 또는 "Other"라고 부릅니다. 둘 다 동일한 토큰을 생성합니다.

앱을 Consumer가 아닌 Business 유형으로 설정합니다. 왼쪽 사이드바에서 Marketing API 제품을 앱에 추가합니다. 앱은 Development Mode로 시작합니다. System User 토큰이 실제 광고에 작동하려면 Live Mode로 전환해야 합니다(아래에 자세히 설명).

Live Mode로 이동하려면 Meta는 공개 개인정보 처리방침 URL과 앱 아이콘(1024×1024 PNG)을 요구합니다. 둘 다 협상 불가입니다. 앱 아이콘이 세련될 필요는 없습니다 — 플레이스홀더로도 충분합니다 — 하지만 URL은 실제로 개인정보 처리방침 페이지로 연결되어야 합니다. 우리는 메인 도메인의 /legal에 호스팅합니다.

3단계: 영구 만료되지 않는 System User 토큰 생성

Business Settings → System Users → [your System User]로 돌아가서 "Generate New Token"을 클릭합니다. 2단계에서 만든 앱을 선택합니다. 그런 다음 권한을 선택합니다.

• ads_management — 캠페인을 만들고 편집하고 일시정지하는 데 필요
• ads_read — insights와 리포팅 데이터를 가져오는 데 필요
• business_management — 자산과 custom conversions를 관리하는 데 필요

만료를 "Never"로 설정합니다. System User 토큰은 진정으로 절대 만료되지 않는 유일한 Meta 토큰입니다 — User Access Token은 최대 60일, Page Token은 파생된 User Token에 따라 다릅니다. 이것이 백엔드 자동화에서 OAuth 대신 System User를 사용하는 전체 이유입니다.

토큰을 즉시 복사합니다. Meta는 한 번만 보여줍니다. secrets manager나 chmod 600이 설정된 .env 파일에 저장합니다. 절대로 git에 커밋하지 않습니다.

4단계: Ad Account와 Page를 자산으로 연결

System User는 존재하지만 아직 어떤 것에도 액세스할 수 없습니다. 자산을 명시적으로 할당해야 합니다. Business Settings → System Users → [your System User] → "Add Assets"를 클릭합니다.

전체 권한("Manage Campaigns" + "Manage Performance")으로 Ad Account를 할당합니다. 전체 권한으로 Page를 할당합니다. 전체 권한으로 Pixel/Dataset을 할당합니다. 여러 Ad Account가 있고 CLI가 모두 관리하기를 원한다면, 각각을 할당합니다.

우리가 이를 설정할 때 act_975780295197610(우리 Ad Account)과 Page 1113585798495892(EMAX Studio 페이지) 그리고 Pixel 1464075091373537을 할당했습니다. Ad Account ID의 act_ 접두사는 API를 호출할 때 필요합니다 — 형식 규칙이 아니라 실제 ID의 일부입니다.

5단계: "Page verwalten" / "Manage Page" 권한 할당

이 단계가 처음에 거의 모든 사람을 함정에 빠뜨리는 단계입니다. 4단계는 Page를 자산으로 할당했지만, 기본 권한 수준은 "Anzeigen erstellen" / "Create Ads"입니다 — 이것으로는 충분하지 않습니다. System User는 Page를 참조하는 광고 크리에이티브를 게시하려면 "Page verwalten" / "Manage Page"가 필요합니다.

이것을 건너뛰면 모든 광고 생성 API 호출이 Page를 언급하지 않는 일반적인 "permission denied" 오류를 반환합니다. 실제 문제는 Page 자산 설정에서 한 번의 클릭 깊이에 있는데, 토큰 범위와 Ad Account 권한을 확인하느라 몇 시간을 보내게 됩니다.

자산 목록에서 Page를 클릭하고 권한으로 스크롤하여 System User에 대해 "Manage Page"를 켭니다. 저장합니다.

6단계: CLI 설치 및 Config 파일 생성

Python의 경우, 공식 SDK를 설치합니다.

pip install facebook-business

Node의 경우, 커뮤니티가 유지 관리하는 클라이언트를 사용합니다.

npm install facebook-nodejs-business-sdk

~/.meta-ads/config.json(또는 스택이 secrets를 저장하는 곳)에 config 파일을 만듭니다.

{
  "access_token": "EAA...your-system-user-token",
  "app_id": "910292175368026",
  "app_secret": "your-app-secret",
  "ad_account_id": "act_975780295197610",
  "page_id": "1113585798495892",
  "pixel_id": "1464075091373537",
  "api_version": "v23.0"
}

권한 설정: chmod 600 ~/.meta-ads/config.json. app_secret은 System User 토큰에 선택사항이지만 Meta가 프로덕션에 권장하는 appsecret_proof 서명을 활성화합니다.

7단계: 첫 번째 테스트 명령 실행

캠페인을 나열하여 모든 것이 작동하는지 확인합니다. Python의 경우:

from facebook_business.api import FacebookAdsApi
from facebook_business.adobjects.adaccount import AdAccount
import json

cfg = json.load(open("/path/to/config.json"))
FacebookAdsApi.init(access_token=cfg["access_token"])
account = AdAccount(cfg["ad_account_id"])
campaigns = account.get_campaigns(fields=["name", "status", "objective"])
for c in campaigns:
    print(c["name"], c["status"], c["objective"])

이것이 리스트(아직 캠페인이 없다면 빈 리스트라도)를 반환하면, 완료된 것입니다. OAuthException이나 Permission denied가 발생하면 아래 오류 표로 돌아갑니다.

일반적인 설정 오류와 해결 방법

이것들은 구축 중에 우리를 물어뜯은 8가지 오류입니다. 모두 실제 시간을 소비했습니다. 고통을 아낍시다.

Custom Conversion 오류가 가장 비열한데, 오류 메시지는 기술적으로 무엇이 잘못되었는지 알려주지만 해결책이 명확하지 않기 때문입니다. 새로 만든 Custom Conversion은 Meta 시스템에서 이벤트가 0개입니다. Meta는 과거 데이터가 없는 것에 대해 캠페인을 최적화하기를 거부합니다. 트릭은 캠페인을 먼저 Landing Page Views로 최적화하여 실행하고, CAPI를 통해 50개 이상의 conversion이 발생하도록 한 다음, Ad Set의 promoted_object를 Custom Conversion ID가 있는 OFFSITE_CONVERSIONS로 전환하는 것입니다. 그 후에는 최적화가 실제로 작동합니다.

실제 첫 캠페인 워크스루

이것은 우리가 첫 라이브 테스트로 실행한 것입니다. 실제 값, 실제 흐름, 실제 결과입니다.

Campaign 만들기. Objective: OUTCOME_TRAFFIC (conversion 데이터가 있으면 나중에 OUTCOME_SALES로 전환). Status: 초기에는 PAUSED로 설정하여 Ad Set과 Ads가 그 아래에 만들어진 후 한 번에 모든 것을 ACTIVE로 전환할 수 있도록 합니다. 우리 설정에서 예산은 Ad Set 수준에서 살아 있습니다.

Ad Set 만들기. 일일 예산: 1000 (센트 = $10/일). 최적화: LANDING_PAGE_VIEWS. 입찰 전략: LOWEST_COST_WITHOUT_CAP. Targeting: 국가 ["US", "GB", "CA"], 연령 25~55세, 언어 영어. Placements: feed, instagram_reels, stories, marketplace. Targeting automation: {"advantage_audience": 1}.

Creatives 구축. 이미지 크리에이티브 3개와 비디오 크리에이티브 3개 — 총 6개 광고. 이미지의 경우, 우리 자체 EMAX Studio 출력을 사용했습니다(eat your own dogfood): 3개 hook, 3개 brand 색상 배경, 모두 1080×1080. 비디오의 경우, 15초 세로형 reels 3개로 word-by-word 자막과 AI 음성을 포함하며, 우리 자체 파이프라인(How to Create an AI Marketing Campaign Step-by-Step에서 워크스루)을 통해 생성되었습니다. 각 비디오 크리에이티브는 썸네일용 image_hash가 필요합니다 — ffmpeg로 1.5초에 프레임을 추출하고, /adimages에 업로드하고, 반환된 hash를 video_data 블록 안에 사용합니다.

활성화. Campaign을 먼저, 그 다음 Ad Set, 그 다음 6개 광고 모두를 ACTIVE로 전환합니다. Meta 검토는 일반적으로 15~30분 안에 통과됩니다. 거부된 광고는 ad.get('effective_status')를 통해 광고별로 표시됩니다.

일일 리포트. meta_daily_report.py 스크립트가 cron을 통해 오전 7시 베를린 시간에 실행됩니다. insights를 가져오고, spend / CTR / CPM / conversions를 Telegram 메시지로 형식화하며, 100개 이상의 impressions 후 CTR이 0.5% 미만인 광고를 자동 일시정지합니다. 처음 48시간 동안 4,200 impressions, 78 클릭(CTR 1.86%), 그리고 12개의 Quick Scan completions가 conversion당 $1.67에 발생했습니다 — 3일째에 QuickScanComplete Custom Conversion에 대해 Landing Page Views에서 OFFSITE_CONVERSIONS로 최적화를 전환하기에 충분한 신호였습니다.

피해야 할 함정

몇 가지가 여러분을 태울 것입니다. 우리는 각각을 어렵게 배웠습니다.

git에 토큰을 하드코딩하지 않습니다. 비공개 repo에서도 안 됩니다. 토큰은 CI 로그, 우발적으로 공개된 fork, 그리고 repo의 가시성이 변경되기 전에 만든 커밋을 통해 누출됩니다. 항상 환경 변수나 repo 외부의 chmod-600 config 파일에서 읽습니다.

5단계의 Page Manage 권한을 건너뛰지 않습니다. 받는 오류는 Ad Account나 토큰에 관한 것처럼 보입니다. 그렇지 않습니다. 크리에이티브 생성 시 모호한 "permission denied"가 보이면 먼저 Page 자산 권한을 재확인합니다.

developer 앱이 여전히 Development Mode에 있는 상태로 배포하지 않습니다. 토큰은 생성한 사용자에게는 작동하지만 다른 System User 컨텍스트에서는 조용히 실패합니다. 서버에서 무엇이든 실행하기 전에 Live Mode로 이동합니다.

비디오 크리에이티브의 image_hash를 잊지 않습니다. 그것 없이는 video_data에 대한 오해의 소지가 있는 오류로 전체 광고 생성이 실패합니다.

확장할 계획이라면 CAPI를 건너뛰지 않습니다. 브라우저 픽셀은 iOS ATT, 광고 차단기, 추적 방지로 인해 30~50%의 이벤트를 잃습니다. 서버 측 Conversions API는 대부분을 다시 캡처합니다 — 광고 지출을 확장하는 첫 주에 갚는 주말 작업입니다.

자주 묻는 질문

Meta Ads CLI를 설정하는 데 비용이 얼마나 들까요?

설정 자체는 무료입니다. Marketing API, System User 토큰, Business Manager, 모든 개발자 도구는 비용이 없습니다 — 실제로 운영하는 광고에 대해서만 지불합니다. 처음에는 설정 시간 4~6시간, 그 이후에는 언제든 30분을 계획합니다.

하나의 CLI 설치로 여러 광고 계정을 운영할 수 있나요?

네, 그리고 이것이 에이전시가 System User 토큰을 사용하는 주된 이유 중 하나입니다. Business Settings에서 각 Ad Account를 자산으로 추가하면, config의 ad_account_id를 변경하거나 파라미터로 전달하여 어느 계정이든 타겟팅할 수 있습니다. 하나의 System User 토큰은 권한만 있으면 여러 Business Manager에 걸쳐 수백 개의 Ad Account를 관리할 수 있습니다.

Google Ads CLI는 어떤가요 — 설정이 비슷한가요?

개념은 비슷하지만 Google의 설정은 더 거칠습니다. Google은 7~21일이 걸릴 수 있는 developer token 승인, 주기적으로 만료되는 OAuth2 refresh token, 그리고 MCC(Manager Account) 권한의 추가 레이어를 요구합니다. Meta의 System User 토큰은 진정으로 두 시스템 중 더 단순한 것입니다. 두 플랫폼을 모두 운영한다면, 패턴을 배우기 위해 Meta를 먼저 설정합니다.

토큰이 손상되면 어떻게 안전하게 회전시키나요?

새 System User 토큰을 생성하고(같은 권한, 같은 "Never" 만료), config를 업데이트하고, 새 토큰이 작동하는지 테스트한 다음, 이전 토큰을 폐기합니다. Meta는 동일한 System User에 대해 여러 활성 토큰을 동시에 유지할 수 있도록 허용하므로, 다운타임 없이 롤할 수 있습니다. 토큰이 유출되면 즉시 폐기하고 권한 없는 캠페인에 대해 API를 통해 최근 광고 지출을 감사합니다.

Conversions API (CAPI)는 이 설정에 어떻게 들어맞나요?

CAPI는 별개이지만 보완적인 시스템입니다. Meta Ads CLI는 캠페인, ad sets, 광고를 관리합니다. CAPI는 해당 광고가 최적화 대상으로 삼는 서버 측 conversion 이벤트를 보냅니다. 둘 다 동일한 Pixel ID를 사용합니다. CAPI 이벤트는 어떤 브라우저 픽셀과도 독립적으로 흐릅니다 — 쿠키가 관여하지 않고 PII가 전송 전에 해시되기 때문에 GDPR-clean 추적의 기초입니다. AI 에이전트로 AI Facebook Ads 운영 개요는 CAPI가 더 큰 자동화 스택에 어떻게 맞는지 다룹니다.

솔직한 결론

Meta Ads CLI는 마법이 아닙니다. 워크플로에서 세 가지를 제거하는 규율 잡힌 방법입니다: OAuth 토큰 새로고침, 수동 Ads Manager 로그인, 그리고 광고를 출시할 때마다 14개 설정을 클릭하는 인적 오류 비용. 실행되면 30분이 걸리던 일을 90초 안에 합니다.

설정이 까다로운 이유는 Meta의 도구가 까다롭기 때문입니다. 하지만 단계들은 결정적입니다. 7단계 설정을 정확히 따르고, 표의 8가지 오류를 주시하며, 오후가 끝날 무렵에는 프로덕션 등급의 광고 스택을 갖게 될 것입니다. CLI가 AI 크리에이티브와 일일 리포팅에 어떻게 연결되는지에 대한 큰 그림은 AI 에이전트로 Facebook Ads 개요와 올해 광고 생태계에서 무엇이 변하고 있는지에 대한 2026년 18주차 AI 뉴스를 참조합니다.

CLI가 라이브가 되면 질문은 어떤 크리에이티브를 공급할 것인가가 됩니다. emax.studio에서 무료 90초 AI-readiness 스캔을 통해 랜딩 페이지를 실행합니다 — 2분 이내에 점수, conversion 격차 목록, 그리고 실행 준비가 된 캠페인 브리핑을 받을 수 있습니다.

EMAX Studio 팔로우: Instagram | YouTube | Facebook