20. 5부·20장 코딩 에이전트 원격 제어
20장 코딩 에이전트 원격 제어
코딩 에이전트를 제대로 써 본 사람은 어느 순간 이런 상상을 하게 된다. "지금 내가 노트북 앞에 없어도, 테스트만 먼저 돌려두고, 에러가 나면 원인까지 찾아서, PR 초안까지 열어주면 얼마나 좋을까?"
바로 여기서 OpenClaw의 진짜 재미가 시작된다. 메신저는 더 이상 알림창이 아니라, 내 개발 환경으로 들어가는 리모컨이 된다. 텔레그램에 한 줄 보내면 Claude Code나 Codex 세션이 살아나고, 로그를 읽고, 테스트를 돌리고, 브랜치를 만들고, 마지막에는 "PR 열어뒀습니다"라고 보고한다. 이 장의 목표는 그 흐름을 마술처럼 보이게 만드는 것이 아니라, 어떻게 하면 안전하게 재현할 수 있는지 손에 잡히게 보여주는 데 있다.
메신저가 개발 콘솔이 되는 순간
원격 제어의 핵심은 단순하다. 당신은 휴대폰으로 지시하고, OpenClaw는 그 말을 알아듣고, 적절한 코딩 런타임을 깨워서 작업을 이어 간다. 여기서 중요한 점은 OpenClaw가 직접 코드를 "예쁘게 써 주는 채팅창"이 아니라, 코딩 하니스(harness, 외부 코딩 엔진을 붙여 쓰는 실행 장치)를 오케스트레이션하는 조정자라는 사실이다.1
이 구조가 강력한 이유는 세 가지다.
메신저에서 시작해도 실제 실행은 Claude Code, Codex 같은 전문 코딩 런타임이 맡는다.
OpenClaw가 세션, 채널, 승인, 보고를 관리하므로 작업이 끊기지 않는다.
Sentry, GitHub, CI 같은 외부 이벤트를 웹훅으로 연결하면 "내가 시키지 않아도 일하는" 파이프라인이 된다.2
쉽게 비유하면 이렇다. Claude Code나 Codex가 손발이라면, OpenClaw는 현장소장이다. 당신은 텔레그램에서 "테스트 깨진 거 잡아줘"라고 말하고, 현장소장은 어느 작업자를 부를지 정하고, 진행 상황을 받아 적고, 위험한 작업에서는 다시 당신에게 확인을 요청한다.
OpenClaw가 Claude Code와 Codex를 다루는 방식
OpenClaw에는 ACP(Agent Client Protocol) 세션이라는 개념이 있다. 이것은 외부 코딩 하니스를 OpenClaw의 세션 체계 안으로 끌어오는 방법이다. 문서 기준으로 Claude Code, Codex, Gemini CLI 같은 도구를 ACP 대상으로 붙일 수 있고, /acp spawn으로 세션을 띄우고 /acp steer로 방향을 수정하며 /acp close로 닫을 수 있다.1
예를 들어 Codex 세션을 지속형으로 시작하고 싶다면 이런 느낌이다.
/acp spawn codex --mode persistent --thread autoClaude Code를 한 번성 작업으로 부르고 싶다면 이렇게 생각하면 된다.
/acp spawn claude --mode oneshot여기서 persistent는 "계속 이어 가는 작업방"이고, oneshot은 "이번 일만 하고 끝나는 단기 알바"에 가깝다. 버그 수정처럼 여러 턴의 대화와 반복이 필요한 일은 persistent가 편하고, "이 로그만 읽고 요약해 줘" 같은 일은 oneshot이 경제적이다.
또 하나 기억할 점이 있다. OpenClaw에서 Codex는 두 가지 경로가 있다. 하나는 openai-codex/... 같은 모델 경로를 통해 OpenClaw 기본 러너로 쓰는 방식이고, 다른 하나는 agentRuntime.id: "codex"로 Codex 앱 서버를 네이티브 런타임으로 붙이는 방식이다. 이름이 비슷해서 헷갈리지만, 전자는 "어떤 인증과 모델을 쓰는가"이고, 후자는 "누가 실제 에이전트 턴을 실행하는가"에 가깝다.3
이 구분을 이해하면 설정에서 길을 덜 잃는다. 모델 이름만 바꿨는데 기대한 동작이 안 나오는 이유가, 사실은 런타임을 바꾸지 않았기 때문인 경우가 많다.
가장 빠른 시나리오: 텔레그램에서 코딩 세션 깨우기
이 장의 가장 중요한 경험은 바로 이것이다. 텔레그램에 들어가서 이렇게 보내는 순간이다.
"claude로 현재 레포 테스트 돌리고 실패 원인 정리해 줘"
이 한 줄 뒤에서 벌어지는 일은 의외로 체계적이다. 먼저 OpenClaw가 텔레그램 DM을 받고, 페어링된 사용자 메시지인지 확인한다. 그다음 ACP 세션 또는 바인딩된 코딩 런타임으로 요청을 넘긴다. 코딩 런타임은 레포지터리를 읽고 테스트를 실행한 뒤, 결과를 다시 OpenClaw로 돌려주고, OpenClaw는 이를 메신저 문장으로 바꿔 전달한다.14
텔레그램 연결 자체는 이미 7장에서 했지만, 코딩 원격 제어 관점에서 꼭 다시 체크할 두 가지가 있다. 첫째, allowFrom으로 허용한 사용자 ID만 메시지를 보낼 수 있어야 한다. 둘째, pairing 승인이 끝난 계정만 실제 제어 권한을 가져야 한다. 텔레그램 연동 가이드도 이 두 단계를 핵심 보안 장치로 설명한다.4
간단한 운영 루틴은 아래처럼 잡으면 좋다.
텔레그램에서 작업 지시를 보낸다.
OpenClaw가 기존 persistent ACP 세션이 있으면 거기에 이어 붙인다.
세션이 없으면 새 코딩 세션을 생성한다.
중간 진행 상황은 짧게, 결과는 구조적으로 보고하게 한다.
이때 SOUL.md나 AGENTS.md에 "코딩 작업 보고 형식"을 미리 적어 두면 훨씬 덜 피곤하다. 예를 들어 "항상 현재 브랜치, 변경 파일 수, 테스트 결과, 다음 액션을 4줄로 요약하라"라고 써 두면, 메신저 대화가 개발 일지처럼 정돈된다.
실전 패턴 1: Claude Code를 텔레그램 승인형으로 붙이기
어떤 개발자는 완전 자동보다 "위험한 순간에만 나를 불러라"를 더 선호한다. 이때 유용한 패턴이 Claude Code Relay다. 구조는 꽤 영리하다. 데스크톱의 Claude Code가 어떤 명령을 실행하려 할 때 HTTP 훅을 쏘고, SSH 터널을 통해 서버의 릴레이 서비스가 그 질문을 받아 텔레그램으로 보낸다. 사용자가 메신저에서 approve 또는 deny를 보내면, OpenClaw가 그 답을 다시 릴레이에 전달하고, Claude Code는 이어서 작업한다.5
즉, 원격 제어인데도 "브레이크 페달"이 남아 있다. 이건 특히 아래 상황에서 빛난다.
git push --force같은 파괴적 명령.env,token,secret처럼 민감 파일 접근rm -rf,sudo,curl | sh같은 위험 패턴
Relay 예시에서는 이런 위험 명령을 자동 감지해 빨간 경고로 보낸다. 그리고 모든 통신은 로컬호스트 바인딩과 SSH 터널을 전제로 하므로 새 포트를 외부에 직접 노출하지 않아도 된다.5
구성 흐름은 이렇다.
데스크톱 쪽
Claude Code 설정 파일에 HTTP 훅을 추가한다.
{
"hooks": {
"PreToolUse": [
{
"type": "http",
"url": "http://localhost:8400/api/question"
}
]
}
}그리고 서버로 8400 포트를 SSH 터널링한다.
ssh -N -L 8400:127.0.0.1:8400 user@your-server서버 쪽
OpenClaw에 텔레그램이 이미 연결되어 있어야 하고, relay 스킬을 설치한 뒤 설정 스크립트를 실행한다. 릴레이는 질문 저장, 텔레그램 알림 발송, 답변 대기, 이력 관리까지 맡는다.5
사용 경험
휴대폰에는 이런 느낌의 메시지가 온다.
🤖 Claude Code wants to run: npm test
Reply in OpenClaw: approve or deny
당신이 approve라고 답하면 다시 노트북 쪽 Claude Code가 일을 계속한다. 즉, 노트북은 계속 켜져 있고, 당신은 침대 위에서 감독만 한다.
이 패턴의 장점은 우아한 실패다. 터널이 죽거나 릴레이가 멈추면, Claude Code는 원래대로 로컬 화면에서 권한 요청을 띄운다. 즉, 원격 승인 기능은 덧붙는 기능이지, 개발 환경을 통째로 망가뜨리는 의존성이 아니다.5
실전 패턴 2: OpenClaw가 Codex 세션을 상시 작업자로 쓰게 만들기
Claude Code가 "실시간 협업형"이라면, Codex는 "상시 투입 가능한 작업자"처럼 운영할 수 있다. 특히 지속형 세션을 쓰면 이전 맥락을 유지한 채 다음 명령을 이어받기 좋다.1
예를 들어 이런 흐름이다.
아침 출근길에 텔레그램으로 말한다.
"어제 checkout 에러 재현하고 failing tests부터 고쳐. 5회 반복마다 진행 보고."
그러면 OpenClaw는 persistent Codex ACP 세션을 만들거나 재개하고, 레포지터리 루트에서 반복 루프를 돌며 테스트를 읽고, 수정하고, 다시 테스트를 돌린다. 중간에 잘 안 풀리면 /acp steer에 해당하는 추가 지시를 자연어로 넣을 수도 있다. 예를 들어 "로그를 더 자세히 남기고 DB 관련 테스트만 먼저 보라"는 식이다.1
이 방식이 좋은 이유는 대화와 작업이 한 방에 묶인다는 데 있다. 그냥 셸 스크립트라면 실패한 뒤 무엇을 생각했는지 남지 않는다. 하지만 ACP 세션은 에이전트가 어떤 가설로 접근했는지, 왜 특정 파일을 고쳤는지, 어디서 막혔는지가 메신저 대화로 축적된다.
여기에 thread 바인딩까지 쓰면 더 편하다. 텔레그램 토픽이나 특정 스레드가 하나의 코딩 세션에 묶여, 그 방에 던진 후속 메시지가 같은 세션으로 계속 흘러간다.1 말하자면 프로젝트별 작업방을 메신저 안에 만드는 셈이다.
실전 패턴 3: Sentry 에러에서 PR 생성까지 닫힌 루프 만들기
이제 가장 흥미로운 부분으로 가 보자. 누가 봐도 "와, 이건 차별화 포인트다" 싶은 흐름이다. 바로 에러 감지부터 PR 생성까지 자동으로 닫는 루프다.
구조는 이렇게 잡으면 된다.
에러가 나면 Sentry가 웹훅을 보낸다. OpenClaw는 그 이벤트를 받아 전용 훅 에이전트 또는 코딩 에이전트에 전달한다. 코딩 에이전트는 관련 레포에서 로그와 코드를 읽고, Claude Code나 Codex 세션을 통해 수정안을 만들고, 테스트를 돌리고, 성공하면 브랜치를 푸시한 뒤 GitHub PR을 생성한다. 마지막으로 텔레그램으로 "PR 링크 + 요약"을 보낸다.26
OpenClaw 웹훅은 게이트웨이에서 활성화할 수 있다. 기본적으로 hooks.enabled, hooks.token, hooks.path를 설정하고, 요청은 Authorization: Bearer <token> 같은 헤더로 인증한다. 중요한 보안 변경으로, /hooks/agent에서 sessionKey를 요청이 마음대로 덮어쓰는 기능은 기본적으로 꺼져 있다. 운영 환경에서는 고정 defaultSessionKey를 두고 접두사 제한을 거는 쪽이 안전하다.7
예시는 대략 이런 느낌이다.
{
"hooks": {
"enabled": true,
"token": "${OPENCLAW_HOOKS_TOKEN}",
"path": "/hooks",
"allowedAgentIds": ["hooks", "main"],
"defaultSessionKey": "hook:ingress",
"allowRequestSessionKey": false,
"allowedSessionKeyPrefixes": ["hook:"]
}
}그리고 Sentry나 중간 오케스트레이터가 이렇게 호출한다.
curl -X POST http://127.0.0.1:18789/hooks/agent \
-H 'Authorization: Bearer SECRET' \
-H 'Content-Type: application/json' \
-d '{
"message": "Sentry error: checkout flow 500. Read the stack trace, reproduce locally, propose a minimal fix, run tests, and if green open a draft PR.",
"name": "Sentry",
"agentId": "hooks",
"wakeMode": "now",
"deliver": true,
"channel": "telegram"
}'이때 제가 추천하는 운영 원칙은 하나다. "한 번에 병을 다 고치지 말고, PR까지를 목표로 하라."
즉, 프로덕션에 바로 배포시키기보다 먼저 다음 단계를 만들게 하는 것이다.
에러 요약
재현 시도
최소 수정
테스트 실행
드래프트 PR 생성
인간 검토 요청
이렇게 하면 자동화의 속도는 살리고, 폭주 가능성은 크게 줄일 수 있다. 커뮤니티 사례에서도 Sentry 웹훅 → 에러 분석 → 수정 → 테스트 → PR 생성 흐름이 실제로 널리 쓰였고, "수동 디버깅 단계를 통째로 줄였다"는 평가가 많았다.6
구현 예시: 텔레그램 한 줄에서 PR까지
이제 조금 더 구체적인 명령형 설계를 보자. 당신의 코딩 에이전트에게 아래와 같은 작업 규칙을 넣었다고 가정하자.
작업 디렉터리는
~/projects/myapp으로 고정한다.모든 변경은 새 브랜치에서만 수행한다.
테스트가 통과해야만 커밋한다.
PR은 항상 draft로 생성한다.
5회 반복마다 텔레그램으로 중간 보고를 보낸다.
그 뒤 메신저에서 이렇게 보낸다.
"auth bug 고쳐. 실패 재현부터 하고, 수정 후 npm test 통과하면 draft PR 열어줘."
이 메시지가 좋은 이유는 다섯 가지 정보를 이미 담고 있기 때문이다. 범위, 순서, 검증 조건, 종료 조건, 산출물. 사람한테 일을 시킬 때도 이 정도는 말해 줘야 덜 삐걱거린다.
에이전트의 내부 플로우는 보통 이런 순서가 된다.
먼저 브랜치를 만든다. 그다음 에러를 재현한다. 재현이 안 되면 로그를 더 모으고, 재현되면 수정에 들어간다. 수정 후에는 테스트를 돌린다. 테스트가 통과하면 커밋 메시지를 만들고 gh pr create --draft로 PR을 연다. 마지막으로 텔레그램에 "원인, 바뀐 파일, 테스트 결과, PR 링크"를 보낸다.6
이 흐름에서 GitHub CLI 인증은 미리 끝내 둬야 한다. 그리고 레포 권한은 가능하면 해당 저장소 범위로 제한하는 편이 좋다. "똑똑한 자동화"는 대개 "잘 묶인 권한" 위에서만 우아해진다.
침대에서 앱을 출시한 사례를 분해해 보기
커뮤니티에서 회자된 "침대에서 앱 출시" 같은 이야기를 과장 광고로만 볼 필요는 없다. 다만 그 장면을 구성하는 부품을 냉정하게 분해해야 한다.
실제로 필요한 것은 거창한 초지능이 아니다.
항상 켜져 있는 OpenClaw
메신저 채널 연결
코딩 하니스 연결(Claude Code 또는 Codex)
GitHub CLI 인증
테스트 및 빌드 스크립트 정리
실패 시 인간 검토 게이트
즉, 드라마틱한 순간도 결국은 잘 정리된 배관 공사 위에 올라간다. 침대에서 앱을 출시했다는 말은 사실 "내가 눕기 전에 배포 파이프라인, 승인 규칙, 브랜치 정책, 테스트 자동화가 다 준비돼 있었다"는 말과 거의 같다.
이 관점이 중요하다. 많은 독자가 여기서 "어떤 프롬프트를 써야 하죠?"를 먼저 묻는다. 하지만 진짜 차이는 프롬프트보다도 실행 환경의 일관성에서 난다. 에이전트가 일할 때마다 작업 디렉터리가 달라지고, 테스트 명령이 자꾸 바뀌고, 환경변수가 들쭉날쭉하면, 원격 제어는 로맨스가 아니라 재난이 된다.
OpenClaw와 Claude Code Channels, 무엇을 같이 쓰고 무엇을 나눌까
2026년 들어 Claude Code Channels가 등장하면서 "그럼 OpenClaw는 필요 없어진 것 아닌가?"라는 말이 많이 나왔다. 하지만 실전에서는 둘의 역할이 꽤 다르다. Channels는 공식 보안 모델과 로컬 세션 제어가 강점이고, OpenClaw는 항상 켜진 데몬, 다양한 채널, 장기 세션, 웹훅 자동화에 강하다.8
특히 이 장의 관점에서는 차이가 분명하다. Channels는 실행 중인 Claude Code 세션을 메신저로 제어하는 데 아주 좋다. 반면 OpenClaw는 메신저, 세션, 웹훅, 멀티 에이전트, 보고, 기억을 한 덩어리로 묶는 데 더 강하다. 그래서 많은 개발자가 다음처럼 역할을 나눠 쓴다.
단순한 원격 코딩 대화는 Channels
지속형 작업자 운영과 외부 이벤트 자동화는 OpenClaw
위험 명령 승인과 메신저 중심 운영은 OpenClaw Relay 패턴
이 책의 독자처럼 1인 창업가나 인디해커라면, 둘 중 하나만 정답이라고 생각할 필요가 없다. 중요한 건 "내가 원하는 자동화가 세션형인가, 상시 운영형인가"를 먼저 구분하는 것이다.8
자주 부딪히는 함정
원격 코딩 자동화는 멋지지만, 함정도 뚜렷하다. 몇 가지는 특히 자주 등장한다.
첫째, 세션이 살아 있지 않은데 살아 있다고 믿는 경우다. Claude Code 계열은 세션 의존성이 강해서, 노트북이 잠들거나 프로세스가 죽으면 메신저는 조용해진다. OpenClaw의 persistent 구조나 tmux, systemd 같은 보조 장치가 필요한 이유가 여기 있다.8
둘째, 권한 프롬프트가 작업을 멈추는 경우다. 이건 오히려 정상이다. 아무 승인 없이 모든 파일 쓰기와 셸 실행을 풀어 두면 처음엔 편하지만, 결국 큰 사고로 돌아온다. 그래서 Relay 같은 "메신저 승인형"이 현실적이다.5
셋째, 코딩 에이전트에게 너무 큰 목표를 한 번에 던지는 경우다. "우리 서비스 결제 버그 전부 잡고 배포해"는 낭만적이지만, 실패 확률이 높다. "에러 재현 → 테스트 추가 → 최소 수정 → draft PR"처럼 잘게 자른 문장이 훨씬 강하다.
넷째, 웹훅을 인터넷에 그대로 노출하는 경우다. OpenClaw 웹훅 문서는 루프백, tailnet, 신뢰된 프록시 뒤에서 운영하고, 전용 훅 토큰을 쓰며, 허용 agentId와 sessionKey 접두사를 제한하라고 권한다.7
다섯째, 채팅 메시지에 비밀을 너무 많이 실어 보내는 경우다. 에러 로그, .env 조각, 토큰 일부가 메신저에 흘러나오지 않도록 보고 형식을 잘라야 한다. "문제 요약"과 "조치 계획"은 보내되, 민감 원문은 서버 로그나 별도 아티팩트에 남기는 편이 낫다.
안전하게 강력해지는 운영 규칙
이 장은 생산성 장이지만, 사실 보안 장의 예고편이기도 하다. 코딩 에이전트 원격 제어는 가장 짜릿한 만큼 가장 위험한 자동화이기 때문이다.
그래서 다음 규칙은 지금부터 습관으로 들이는 편이 좋다.
첫째, main 브랜치에 직접 쓰지 말 것. 에이전트는 늘 feature branch에서 움직이게 하라.
둘째, 테스트 통과를 종료 조건에 넣을 것. "수정했다"가 아니라 "검증됐다"가 끝이다.
셋째, PR 생성까지는 자동화해도 merge는 사람 손으로 할 것. 적어도 개인 프로젝트라도 이 경계는 오래 도움이 된다.
넷째, 위험 명령은 승인형으로 둘 것. force push, 대량 삭제, 비밀 파일 접근은 메시지 승인 없이는 진행하지 않게 하라.5
다섯째, 웹훅 에이전트는 별도로 둘 것. 일반 대화 에이전트와 외부 이벤트 수신 에이전트를 분리하면 폭발 반경이 줄어든다.7
여섯째, 작업 디렉터리와 사용 도구를 고정할 것. "어디서 일해야 하는지 모르는 에이전트"는 곧 "아무 데나 건드리는 에이전트"가 된다.
일곱째, 실패 보고를 예쁘게 만들 것. 실패 자체보다 무서운 것은 조용한 실패다. 실패 시에는 반드시 원인, 마지막 명령, 다음 권장 액션을 보내게 하라.
오늘 바로 따라 할 수 있는 최소 셋업
이 장을 읽고 당장 해볼 수 있는 가장 작은 실습은 다음이다.
텔레그램으로 OpenClaw에 메시지를 보낼 수 있는 상태에서, Claude Code 또는 Codex 중 하나를 ACP 세션으로 붙인다. 그리고 레포 하나를 정해 "테스트 실행 → 실패 요약 → 수정 제안"까지만 시킨다. PR 생성은 두 번째 단계로 미뤄도 좋다.
처음 목표는 이렇게 잡자.
"내가 외출 중에 폰으로 테스트를 돌리고, 실패 이유를 받아볼 수 있다."
그다음 목표는 이렇다.
"실패를 수정하고 draft PR까지 열 수 있다."
마지막 목표는 여기다.
"Sentry 에러가 들어오면 자동으로 재현·수정·테스트·PR까지 이어지고, 나는 마지막 승인만 한다."
이 순서가 중요한 이유는, 자동화의 신뢰는 한 번에 완성되지 않기 때문이다. 처음부터 무인 공장을 만들려 하지 말고, 먼저 "나 대신 테스트 돌려주는 조수"부터 만들자. 조수가 믿을 만해지면, 그다음에 "PR 초안까지 만드는 주니어 개발자"로 키우면 된다.
OpenClaw의 코딩 원격 제어가 강력한 이유는 여기에 있다. 단순히 채팅으로 코드를 만지는 데 그치지 않는다. 당신의 개발 환경에 메신저라는 손잡이를 달고, 세션과 승인과 보고와 자동화를 한 흐름으로 엮는다. 잘 세팅한 뒤에는 정말 이상한 경험을 하게 된다. 산책 중인데 버그가 고쳐지고, 침대에 누웠는데 PR이 올라오고, 아침에 일어나 보니 "검토만 하면 되는 상태"가 되어 있다.
그때 비로소 느끼게 된다. 아, 이제 메신저가 메신저가 아니구나. 내 두 번째 터미널이 되었구나.
참고
2Automation OpenClaw Skills Library
4텔레그램으로 Claude Code 실행하기 3편 - OpenClaw에 텔레그램 연동하기
5Claude Code Relay — Remote control for Claude Code through Telegram via OpenClaw
6OpenClaw Autonomous Coding: How Developers Fix Bugs and Open PRs From Their Phones
8Claude Code Channels: Control Your AI Coding Agent From Telegram Setup + OpenClaw Comparison
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.