들어가는 말
1인 개발사를 운영하면서 개발 작업의 상당 부분을 OpenClaw 에이전트에게 맡기고 있다. 작업 방식은 다음과 같다. 먼저 내가 구현하려는 기능(feature)에 대한 전체적인 개발 계획을 수립하고 이를 단계(phase) 별로 나눈다. 다음으로 에이전트에게 한 단계의 개발 진행을 요청한다. 그러면 에이전트가 "Claude Code 서브에이전트에게 코딩시켜 놓고, 결과 나오면 다시 알려줄게."라고 답하며 Claude Code 서브에이전트를 생성해서 백그라운드에서 구동시킨다. 모든 개발 단계가 끝날 때까지 과정이 반복되는 패턴이다.

그런데 이 방식에는 두 가지 문제가 있다. 첫번째 문제는 나는 에이전트에게 구현하려는 기능과 방향성만 제시하고 최대한 자동화를 하고 싶은데, 개발 프로세스를 직접 챙겨야 한다는 점이다. 두 번째는 개발 작업이 백그라운드에서 진행되다 보니 어떻게 돌아가는지 눈으로 확인할 방법이 없다는 것이다.
이번에 ACP를 도입하면서 이 두 가지가 해결됐다. OpenClaw 메인 에이전트가 개발팀장 역할을 맡고, 나는 Discord 채널에서 큰 방향만 전달하면 된다. 에이전트가 ACP로 바인딩된 Claude Code 스레드에서 구체적인 구현을 지시하고, 둘이 주고받는 대화를 나는 수시로 확인(관망)할 수 있다. CEO가 팀장한테 방향을 제시하고, 팀장이 개발자와 협업하는 구조다. 그리고 ACP 도입의 보너스가 하나 더 있다. 사실 Claude Pro(또는 Max) 구독을 OpenClaw OAuth로 직접 대량 호출하는 건 약관상 애매한 영역이라 계정 정지로 이어질 수 있다. 하지만 Claude Code는 Anthropic이 코딩 자동화를 위해 공식 설계한 도구라 그런 걱정이 없다.
https://apps.apple.com/kr/app/id6757746167
독서 잔디 앱 - App Store
App Store에서 Garibong Labs의 독서 잔디 앱을 다운로드하십시오. 스크린샷, 평가 및 리뷰, 사용자 팁 및 독서 잔디 앱과 비슷한 다른 앱을 볼 수 있습니다.
apps.apple.com
이 글에서는 '독서잔디'라는 iOS 앱 개발에 ACP를 실제로 적용한 경험을 정리한다. ACP가 (나를 포함한) OpenClaw 유저들에게 아직 생소한 기능이라서 개념부터 설치, 설정, 실사용까지 최대한 자세히 다룬다.
ACP란 무엇인가
개요
ACP는 Agent Client Protocol의 약자다. 한 줄로 정리하면 OpenClaw가 외부 코딩 하네스를 채팅 인터페이스에서 직접 실행하는 프로토콜이다. 여기서 '하네스(harness)'는 특정 작업을 수행하도록 설계된 에이전트 실행 환경을 뜻한다. Claude Code, Codex, Gemini CLI 같은 코딩 전문 도구들이 각각 하나의 하네스다.
https://code.claude.com/docs/ko/how-claude-code-works
Claude Code의 작동 방식 - Claude Code Docs
에이전트 루프, 내장 도구, Claude Code가 프로젝트와 상호작용하는 방식을 이해합니다.
code.claude.com
위에서 언급한 코딩에 특화된 전문 도구들(Claude Code, Codex, Pi, OpenCode, Gemini CLI 등)은 터미널에서 실행되며 파일을 읽고 코드를 수정하고 빌드를 돌리는 데에 최적화돼 있다. ACP는 이 도구들을 OpenClaw 채널(Discord, Telegram 등)에 연결해서 채팅창에서 직접 명령할 수 있게 한다.
일반 OpenClaw 실행 방식과의 차이
OpenClaw에서 코딩 작업을 시키는 방법은 두 가지가 있다.
서브에이전트 방식
기본 방식이다. OpenClaw 자체가 모델을 호출해서 코드를 작성한다. 파일 접근은 OpenClaw 샌드박스 안에서 이뤄지고, 빌드나 테스트 실행은 별도 설정이 필요하다.
ACP 방식
외부 코딩 하네스를 실행한다. Claude Code나 Codex가 호스트에서 직접 돌아간다. 로컬 파일시스템에 자유롭게 접근하고 xcodebuild나 npm test 같은 빌드 명령을 실제로 실행하고, 결과를 확인한다. 항목별로 비교하자면 아래 표와 같다.
| 서브에이전트 | ACP 세션 | |
| 런타임 | OpenClaw 네이티브 | 외부 코딩 하네스 (acpx 백엔드) |
| 파일 접근 | OpenClaw 샌드박스 | 호스트 파일시스템 직접 |
| 빌드 실행 | 별도 설정 필요 | 직접 가능 |
| 세션 키 | agent:<id>:subagent:<uuid> |
agent:<id>:acp:<uuid> |
| 주요 명령 | /subagents ... |
/acp ... |
| 지속 세션 | 1회성 기본 | 가능 (persistent 모드) |
OpenClaw 에이전트를 이용한 코딩 자동화가 목적이라면 ACP를 사용하는 것이 더 적절하다. 서브에이전트는 '정보 조회나 간단한 글쓰기'에 어울리고, ACP는 '실제 코드 작성과 빌드'에 더 어울린다.
실행 흐름

acpx는 OpenClaw의 ACP 백엔드 플러그인이다. Claude Code나 Codex를 서브프로세스로 실행하고 OpenClaw와 통신을 중계한다. 실제로 코드를 건드리는 건 Claude Code나 Codex이고, OpenClaw는 채팅 인터페이스 역할을 한다.
세션 모드
ACP 세션은 두 가지 모드로 동작한다.
persistent (지속 세션)
세션이 유지된다. 첫 명령으로 시작한 세션에 계속 이어서 지시할 수 있다. 컨텍스트가 쌓여서 에이전트가 "이전에 무슨 작업을 했는지" 기억한다. 장기 개발 작업에 적합하다.
oneshot (1회성)
작업 완료 후 세션이 종료된다. 독립적인 단발성 태스크에 적합하다.
사전 준비
1. Claude Code 설치
npm install -g @anthropic-ai/claude-code
설치 후 인증:
claude login
Claude Pro(또는 Max) 구독 계정으로 로그인한다. ~/.claude/에 인증 정보가 저장된다. ACP가 이걸 사용해서 Claude Code를 실행한다. OpenClaw ACP는 Codex, Gemini CLI 등도 지원한다. 이 포스트에 따로 다루지는 않지만 설치 및 인증을 진행하고 사용하면 된다.
2. openclaw.json 설정: 에이전트 등록
OpenClaw 설정 파일에 ACP 에이전트를 등록한다. 설정 파일은 보통 ~/.config/openclaw/openclaw.json 또는 openclaw configure로 접근한다. 직접 수정하는 것보다 에이전트에 설정해 달라고 요청하는 것이 편하고 오히려 안전하다.
{
agents: {
list: [
{
id: "claude",
runtime: {
type: "acp",
acp: {
agent: "claude",
backend: "acpx",
mode: "persistent",
cwd: "/Users/username/Projects/my-ios-app"
}
}
}
]
}
}
각 필드 설명:
id: OpenClaw에서 이 에이전트를 부를 이름./acp spawn claude에서claude가 이 값runtime.type: "acp": 이 에이전트가 ACP 방식으로 실행된다는 선언runtime.acp.agent: 실제로 실행할 하네스."claude"(Claude Code),"codex","gemini"등runtime.acp.backend: "acpx": ACP 브릿지 플러그인 지정. 현재 기본값runtime.acp.mode:"persistent"또는"oneshot"runtime.acp.cwd: 에이전트가 작업할 기본 디렉터리. 프로젝트 루트로 설정하면 편하다
설치 챕터에서도 언급했지만 Cluade Code 뿐 아니라 Codex, Gemini CLI 같은 여러 코딩 에이전트를 등록해서 필요에 따라 골라 쓸 수 있다.
{
agents: {
list: [
{
id: "claude",
runtime: {
type: "acp",
acp: {
agent: "claude",
backend: "acpx",
mode: "persistent",
cwd: "/Users/username/Projects/ios-app"
}
}
},
{
id: "codex",
runtime: {
type: "acp",
acp: {
agent: "codex",
backend: "acpx",
mode: "persistent",
cwd: "/Users/username/Projects/web-app"
}
}
}
]
}
}
3. Discord 스레드 바인딩 활성화
Discord에서 /acp spawn으로 스레드를 열려면 추가 설정이 필요하다. 이게 없으면 스레드 바인딩이 작동하지 않는다. 마찬가지로 에이전트에게 자연어로 요청해도 된다.
{
channels: {
discord: {
threadBindings: {
spawnAcpSessions: true
}
}
}
}
Telegram을 쓴다면 아래와 같이 설정한다.
{
channels: {
telegram: {
threadBindings: {
spawnAcpSessions: true
}
}
}
}
4. 특정 채널에 영구 바인딩 (선택)
특정 Discord 채널을 ACP 세션에 고정하고 싶다면 bindings 설정을 추가한다. 이렇게 하면 해당 채널에서 오는 모든 메시지가 자동으로 ACP 세션으로 라우팅된다.
{
bindings: [
{
type: "acp",
agentId: "claude",
match: {
channel: "discord",
accountId: "default",
peer: { kind: "channel", id: "채널ID" }
},
acp: { label: "ios-dev" }
}
]
}
이 방식은 개발 전용 채널을 만들고 거기서 바로 Claude Code와 대화하고 싶을 때 유용하다. 나는 필요시에만 채널에 스레드를 열어서 개발하는 방식을 쓰기 때문에 이 부분은 설정하지 않았다.
Discord에서 ACP 실행하기
슬래시 커맨드로 세션 시작
Discord에서는 슬래시 커맨드를 한 줄로 입력할 수 없다(아는 분이 있으면 좀 알려주시길). /acp를 입력하면 Discord UI가 action과 value 필드를 순서대로 물어본다.


/acp입력- action 필드:
spawn선택 - value 필드:
claude --mode persistent --thread auto --cwd /path/to/project입력



각 옵션 설명:
claude: 앞서 등록한 에이전트 ID--mode persistent: 대화가 유지되는 세션--thread auto: 스레드 안이면 그 스레드에 바인딩, 밖이면 새 스레드 생성
실행하면 스레드가 열리고 Claude Code가 초기화된다. 이후 그 스레드에서 계속 지시하면 같은 세션이 이어진다. thread 옵션은 아래 표로 정리했다.
| 옵션 | 동작 |
| --thread auto | 스레드 안이면 바인딩, 밖이면 새 스레드 생성 |
| --thread here | 현재 스레드에 바인딩. 스레드 아니면 실패 |
| --thread off | 바인딩 없음. 세션만 시작 |
Discord에서 Claude Code가 별도 앱으로 보이는 원리
ACP 세션을 스레드에 바인딩하면 Claude Code의 메시지가 OpenClaw 봇 이름이 아니라 "⚙ claude" 라는 별도 앱 이름으로 표시된다. 이게 어떻게 작동하는지 알아두면 유용하다.

OpenClaw는 ACP 스레드 바인딩 시 Discord Webhook을 생성하려고 시도한다. 이 webhook으로 메시지를 보낼 때 username: "⚙ claude" 파라미터를 설정하면 Discord에서 별도 앱처럼 표시된다.
1. /acp spawn claude --thread auto 실행
2. OpenClaw → bindTarget() 호출 → 채널에 "OpenClaw Agents" 이름의 webhook 생성 시도
3. webhook 생성 성공 → webhookId/webhookToken 저장
4. ACP 출력 전송 시 → sendWebhookMessageDiscord() → username: "⚙ claude" 로 전송
5. Discord에서 "⚙ claude" 앱으로 별도 표시 ✅
주의: MANAGE_WEBHOOKS 권한 필요
webhook 생성에는 MANAGE_WEBHOOKS 권한이 필요하다. OpenClaw 봇에 이 권한이 없으면 webhook 생성에 실패하고, 대신 봇 본인 이름으로 fallback 전송된다. Claude Code 메시지가 봇 이름으로 표시되면 이 권한이 빠진 것이다.

Discord 서버 설정에서 OpenClaw 봇에 MANAGE_WEBHOOKS 권한을 부여하면 "⚙ claude" 별도 앱 표시가 된다.
세션 관리
/acp status # 현재 ACP 세션 상태 확인
/acp steer # 컨텍스트 유지하면서 방향 조정
/acp cancel # 현재 작업 중단
/acp close # 세션 종료 + 스레드 바인딩 제거
실제로 자주 쓰게 되는 건 status와 close 두 가지다. 작업이 끝나면 close로 세션을 닫아야 스레드 바인딩이 정리된다. steer는 세션을 새로 시작하지 않고 방향을 바꿀 때 쓸 수 있는 커맨드인데, 실제로는 스레드에서 직접 메시지로 지시하는 경우가 대부분이다.
자연어 요청 (더 편한 방법)
Discord에서 /acp 슬래시 커맨드는 UI가 action/value를 순서대로 묻는 방식이라 번거롭다. 더 간단한 방법은 OpenClaw 에이전트에게 자연어로 말하는 것이다. 에이전트가 sessions_spawn으로 ACP 세션을 직접 열어준다. 채널에서 이렇게 말하면 된다.
Claude Code를 이 채널 스레드에서 persistent 모드로 시작해줘. cwd(작업 디렉토리)는 /Users/username/Projects/my-ios-app로 설정해줘.
에이전트가 내부적으로 sessions_spawn(runtime: "acp", agentId: "claude", thread: true, mode: "session", cwd: "...")을 호출한다. 슬래시 커맨드 UI 없이 스레드가 열리고 Claude Code가 지정한 프로젝트 디렉터리에서 바로 시작된다.
실전: 독서잔디 v1.6 TabView 구현
독서잔디(독서 습관 추적 iOS 앱)에 TabView 4탭 구조를 추가하는 작업을 ACP로 진행했다. 기존에는 HomeView 하나에 모든 기능이 몰려 있었다. 홈/서재/통계/설정 탭으로 나누는 작업이다. 아래는 최종 결과물이다.

실제 워크플로
작업은 이렇게 진행됐다. 나는 #ios-reading-garden 채널에서 OpenClaw 에이전트에게 작업 방향만 전달했다:
독서잔디에 TabView 4탭 구조 추가해줘.
홈/서재/통계/설정 탭으로 나눠서.
에이전트가 이 요청을 받아 ACP 세션에 바인딩된 스레드에서 Claude Code에 구체적인 구현 지시를 내렸다. 나는 스레드에서 에이전트와 Claude Code가 주고받는 대화를 수시로 확인했지만 직접 참여하지는 않았다. 에이전트가 스펙을 정하고, Claude Code가 파일을 작성하고, 에이전트가 결과를 검토하는 과정이 스레드에서 그대로 펼쳐졌다.


서브에이전트 방식(이전)에서는 내가 에이전트에게 상세 스펙을 지시하면 에이전트가 Claude Code 서브에이전트를 생성(백그라운드)했다. 개발 진행 과정은 확인할 수 없고 결과만 전달받았다. 이에 비해서 ACP 방식은 내가 에이전트에게 개발 방향만 전달하면 에이전트가 Claude Code에게 상세 작업 지시를 내리고, Claude Code가 에이전트에게 보고하는 과정이 반복된다. 나는 이 과정을 스레드에서 이뤄지는 둘의 대화를 보면서 확인한다. 필요시에만 스레드 외부에서 에이전트와 소통한다.

Claude Code가 받은 태스크
OpenClaw 에이전트가 Claude Code에 전달한 구체적 지시 사항은 다음과 같다. iOS 앱 개발, 그것도 내 프로젝트에 한정된 내용이라 그냥 쓱 보고 넘어가면 된다.
TabView 4탭 구조 구현해줘
- 홈 (기존 HomeView)
- 서재 (LibraryView)
- 통계 (StatsTab, placeholder. 이번달/올해/연속기록 기본 수치)
- 설정 (SettingsTab, 일반/데이터/정보 섹션)
작업 상세
- MainTabView.swift 신규 작성
- ReadingGardenApp.swift에서 HomeView() → MainTabView() 교체
- 기존 HomeView 최상위 NavigationStack 제거 (HomeTab이 대신 감쌈)
- project.pbxproj에 새 파일 등록
- xcodebuild로 빌드 확인돼어야 완료
Claude Code가 한 일
신규 스크립트 생성
Views/Main/MainTabView.swift: 4탭 TabView, iOS 26 Liquid Glass 자동 적용Views/Home/HomeTab.swift: NavigationStack wrapperViews/Library/LibraryTab.swift: NavigationStack wrapperViews/Stats/StatsTab.swift: placeholder + 기본 수치Views/Settings/SettingsTab.swift: 일반/데이터/정보 섹션
기존 스크립트 수정
ReadingGardenApp.swift: 진입점 교체HomeView.swift: 최상위 NavigationStack 제거project.pbxproj: 새 파일 등록, deployment target 통일
생성된 MainTabView.swift:
struct MainTabView: View {
var body: some View {
TabView {
Tab("홈", systemImage: "leaf") {
HomeTab()
}
Tab("서재", systemImage: "books.vertical") {
LibraryTab()
}
Tab("통계", systemImage: "chart.bar") {
StatsTab()
}
Tab("설정", systemImage: "gearshape") {
SettingsTab()
}
}
.tint(GardenColors.primaryGreen)
}
}
Claude Code가 빌드에 성공한 것을 OpenClaw 에이전트가 확인하고 시뮬레이터에서 확인한 뒤 Github 저장소에 PR을 올렸다. 내가 최종적으로 간단히 코드 리뷰를 진행하고 머지했다. 이렇게 iOS 앱의 신규 기능에 대한 개발 작업이 끝났다.
자동화 팁 & 주의사항
일부 항목은 iOS 앱 개발에 한정된 내용도 있지만 전반적인 (Claude Code를 이용한) ACP 개발에 참고할 만한 내용이라 빼지 않았다.
자동화가 용이한 태스크
- 명세가 명확한 구현 태스크 (파일 추가, 구조 리팩토링)
- 빌드 확인이 필요한 작업: Claude Code가
xcodebuild를 직접 돌린다 - 반복적인 보일러플레이트 (Localization 파일, 설정 화면, 테스트 코드)
- 설계 문서가 먼저 있는 경우 (UI spec → 구현 설계 → 구현 순서로 Phase 분할)
따로 신경 써야 하는 것들
.pbxproj파일 등록: CLI로 Swift 파일을 추가하면 Xcode 프로젝트 파일에 자동 등록이 안 되는 경우가 있다. 커밋 전에 반드시 빌드 확인. Claude Code는xcodebuild로 이걸 잡아낸다.- 컨텍스트 길이: 작업 범위가 넓으면 한 번에 다 넣지 말고 Phase로 나눠서 지시한다. "Phase 1: TabView 골격 → Phase 2: 각 탭 상세 구현" 식으로.
- 인증 만료:
claude login상태가 끊기면 ACP 세션이 조용히 실패한다.claude --version으로 미리 확인해 두자. - 샌드박스 세션 제한: OpenClaw 샌드박스 안에서는
/acp spawn을 쓸 수 없다.Sandboxed sessions cannot spawn ACP sessions라는 에러가 나온다. 호스트 세션에서 실행해야 한다. 디스코드에서 슬래시 명령어로 실행하거나 에이전트에게 자연어로 요청하는 일반적인 경우는 모두 호스트 세션이라 사실 따로 신경쓸 건 없다.
Claude OAuth 직접 사용 vs ACP
중요한 내용이라 다시 한번 언급한다. OpenClaw를 Claude OAuth 토큰으로 바로 쓰는 건 개인 구독을 자동화에 쓰는 셈이라 계정 정지 위험이 있다. Claude Code는 Anthropic이 코딩 자동화를 위해 만든 공식 도구다. ACP로 경유하면 같은 구독으로 안전하게, 그리고 더 강력한 코딩 에이전트 기능(파일 편집, 빌드 실행, 세션 재개)을 쓸 수 있다.
정리
- ACP는 OpenClaw에서 Claude Code나 Codex 같은 외부 코딩 하네스를 채팅에서 실행하는 프로토콜이다.
- ACP 설정은
openclaw.json에 다음을 추가하거나 에이전트에게 자연어로 요청한다.- 에이전트 등록:
runtime.type: "acp" - Discord 설정:
threadBindings.spawnAcpSessions: true
- 에이전트 등록:
- ACP 세션 시작은 다음 슬래시 명령어를 사용하거나 에이전트에게 자연어로 요청한다.
/acp spawn claude --mode persistent --thread auto
- ACP를 사용하면 Claude Pro(또는 Max) 구독으로 계정 정지 걱정 없이 OpenClaw 코딩 자동화를 쓸 수 있다.
- 작업 방식에 있어 나는 개발 방향성만 제시하고 나머지는 위임한다. 작업이 돌아가는 동안 나는 다른 일을 하거나 쉴 수 있다.
- 스레드에서 OpenClaw 에이전트와 Claude Code가 나누는 대화를 실시간으로 볼 수 있다. 이전 서브에이전트 방식과 가장 다른 점이다.
참고 자료
https://docs.openclaw.ai/tools/acp-agents
ACP Agents - OpenClaw
/acp statusShow backend, mode, state, runtime options, capabilities./acp status
docs.openclaw.ai
끝.
'AI-Agent > OpenClaw-Guide' 카테고리의 다른 글
| 공모주 청약 일정을 OpenClaw로 구글 캘린더에 자동 등록하기 (0) | 2026.03.08 |
|---|---|
| ChatGPT Pro 구독 플랜으로 추가 과금 없이 OpenClaw에서 GPT 모델 사용하기 (0) | 2026.03.04 |
| OpenClaw 운영 가이드 - 멀티봇 환경에서 에이전트별 모델 fallback 설정으로 Rate Limit 방지하기 (0) | 2026.02.25 |
| OpenClaw 운영 가이드 - OpenClaw 버전 업데이트 중 오류 발생 시 복구(rollback) 방법 정리 (0) | 2026.02.17 |
| OpenClaw 활용 가이드 - 한 지붕 두 에이전트, 서브 에이전트 생성부터 디스코드 채널 입장까지 (2) | 2026.02.09 |