Emacs에서 LLM 에이전트 쓰는 법: Agent-shell+ACP 입문

Agent-shell은 Emacs 안에 “에이전트 전용 셸 버퍼”를 만들고, ACP(Agent Client Protocol)로 다양한 LLM 에이전트와 대화하게 해주는 프로젝트입니다. 한마디로, 웹브라우저·별도 앱·에디터 플러그인 사이를 왔다 갔다 하지 않고도 Emacs 버퍼에서 에이전트를 ‘프로세스처럼’ 붙잡고 일시키는 방식이죠.

이 글에서는 Agent-shell이 왜 ACP 기반으로 설계됐는지, MELPA 설치부터 환경 변수 설정, 에이전트 실행/기본값 지정, MCP 서버 연결, 컨테이너(도커)로 안전하게 돌리는 방법까지 “처음 써보는 사람 기준”으로 흐름을 잡아드립니다.

Agent-shell이 해결하는 문제: 에이전트 난립 시대의 ‘고정 좌석’

요즘 에이전트는 많습니다. 그런데 문제는 “어디서 어떻게 쓰느냐”가 제각각이라는 점이에요. 어떤 건 웹 UI, 어떤 건 독자 CLI, 어떤 건 특정 IDE에만 붙습니다. 결국 도구가 늘수록 컨텍스트 스위칭이 늘고, 설정은 더 복잡해지죠.

ACP는 이 혼란을 줄이려는 표준 레이어입니다. 에디터(클라이언트)와 에이전트(서버)가 JSON-RPC로 대화하는 공통 규격을 갖추면, “에디터는 한 번만 연동하고 에이전트는 갈아끼우는” 구조가 됩니다. LSP가 언어 도구 생태계를 정리했던 것처럼, ACP는 에이전트 생태계를 정리하려는 접근이에요.¹

Agent-shell은 바로 그 ACP를 Emacs의 버퍼/프로세스 문화에 맞게 얹은 셈입니다. 그래서 체감은 “채팅 앱”보다는 “comint 기반 REPL/셸”에 가깝습니다. 키보드 중심으로 쭉 밀고 가는 Emacs 사용자에게 특히 자연스럽죠.

설치: MELPA로 시작하고, 핵심은 acp.el 이해하기

Agent-shell의 첫 단추는 MELPA 설치입니다. Emacs 패키지 설치 흐름이 익숙하다면, 여기까지는 5분 컷이에요. 중요한 건 그 다음입니다. Agent-shell은 혼자서 모든 걸 하지 않습니다. ACP 통신을 구현해주는 기반 레이어가 필요하고, 그 역할을 하는 것이 acp.el 계열입니다.

정리하면 이렇게 보면 편합니다. Agent-shell은 “대화가 오가는 UI/버퍼/명령어”에 가깝고, acp.el은 “ACP로 말하게 해주는 통신 엔진”입니다. 그래서 뭔가가 안 될 때는 대개 두 군데 중 하나에서 이슈가 납니다. 버퍼 동작(입력/출력/세션) 문제인지, ACP 프로세스/JSON-RPC 문제인지부터 나누면 트러블슈팅이 훨씬 쉬워집니다.

버전 업데이트(예: 0.17, 0.25 라인업)에서 자주 등장하는 포인트도 대부분 “더 많은 에이전트/클라이언트와의 호환”과 “설정/의존성 관리의 마찰 제거”에 맞춰져 있다고 이해하면 맥락이 잡힙니다.

의존성 설치: 에이전트마다 ‘필수 도구’가 다르다

Agent-shell을 설치했다고 끝이 아닙니다. 실제로는 “어떤 ACP 에이전트를 붙일 건지”에 따라 외부 도구가 달라집니다. 예를 들어 OpenHands 같은 에이전트는 자체 CLI를 제공하고, ACP 모드로 실행하는 진입점도 그 CLI가 담당합니다.¹

이 구조의 장점은 명확합니다. Emacs는 ACP로만 말하고, 에이전트 런타임은 각 에이전트가 알아서 챙깁니다. 대신 사용자는 에이전트별 설치를 한 번은 해줘야 해요. 여기서 팁은 간단합니다.

첫째, “Emacs 패키지 설치”와 “에이전트 CLI 설치”를 ذهن속에서 분리하세요. Emacs는 인터페이스고, 에이전트는 별도 프로그램입니다.

둘째, 에이전트 CLI가 업데이트되면 ACP 동작도 같이 바뀔 수 있습니다. 갑자기 대화가 안 되면 Emacs 쪽보다 먼저 에이전트 CLI 버전을 의심해보는 게 의외로 빠릅니다.

환경 변수 설정: API 키 vs 로그인, 무엇이 덜 귀찮을까?

Agent-shell을 제대로 쓰려면 결국 인증을 통과해야 합니다. 보통은 API 키 기반이 가장 단순합니다. 환경 변수로 키를 넣고, Emacs에서 에이전트를 띄우면 끝이니까요.

다만 팀/회사 환경이나 여러 모델을 번갈아 쓰는 상황이라면 “로그인 기반 인증”이 편할 때도 있습니다. 에이전트 CLI가 자체적으로 인증 토큰을 관리해주면, Emacs는 굳이 비밀을 들고 있지 않아도 되거든요. 이 관점은 도커/샌드박스 같은 격리 환경과도 잘 맞습니다. 즉, “에이전트는 모델 제공자에만 인증하고, 나머지 도구 인증은 도구(MCP)가 가진다”는 방향으로 가면 보안/운영이 깔끔해지는 편입니다.²

정리하면 선택 기준은 이렇습니다. 혼자 쓰고 빠르게 시작하려면 API 키가 가장 쉽고, 여러 도구/자격증명이 얽히면 로그인/토큰 관리 쪽이 장기적으로 편합니다.

사용법: 에이전트 실행, 디폴트 지정, MCP 서버까지 연결하기

Agent-shell의 재미는 “특정 에이전트를 띄워서 그 버퍼를 한 프로젝트의 작업실로 쓰는 것”에 있습니다. 실전에서는 보통 다음 순서로 굴러갑니다.

먼저, 명령으로 에이전트를 시작합니다. 이때 에이전트는 Emacs의 서브프로세스처럼 떠 있고, 버퍼는 대화 로그와 명령 입력창 역할을 합니다. 이 구조 덕분에 Emacs의 장점(검색, 복사, 기록, 버퍼 분리)이 그대로 살아납니다.

다음은 디폴트 에이전트 설정입니다. 여러 에이전트를 테스트하다 보면 “항상 쓰는 1개”가 생기는데, 이걸 기본값으로 박아두면 매번 고르는 시간을 줄일 수 있어요. 특히 일상 작업(리팩터링, 문서 초안, 테스트 작성)은 같은 성격의 에이전트가 반복해서 처리하니 효과가 큽니다.

마지막은 MCP 서버 연결입니다. 여기서 Agent-shell의 활용도가 확 올라갑니다. MCP는 에이전트가 외부 도구를 쓰게 해주는 공통 인터페이스로, 데이터베이스·GitHub·사내 API 같은 것을 “도구로 노출”할 때 자주 쓰입니다. 도커 쪽에서는 MCP 서버를 컨테이너로 배포하고, 게이트웨이로 라우팅/인증을 묶어 운영 복잡도를 줄이려는 흐름도 강합니다.³ Emacs에서 에이전트를 쓰더라도, 실제 툴은 MCP로 연결하면 “에이전트 교체”와 “툴 교체”를 분리할 수 있어 유지보수가 편해집니다.

도커/컨테이너: ‘안전하게’ 에이전트를 굴리는 가장 현실적인 방법

에이전트에게 로컬 파일과 명령 실행 권한을 주는 순간, 편리함과 위험이 동시에 생깁니다. 최근에는 실수로 파일이 삭제되는 사례가 커뮤니티에서 종종 회자되며, “에이전트는 컨테이너 안에서만 돌려라”가 준-상식처럼 번지고 있어요.²

이때 컨테이너 전략은 단순한 보안뿐 아니라 재현성에도 도움이 됩니다. 에이전트 런타임(Python/Node/기타)과 의존성을 통째로 고정할 수 있으니까요. 그리고 비밀정보(토큰, 키) 주입도 컨테이너 런타임에서 통제하기 쉬워집니다. 도커는 MCP 서버 운영에서도 같은 이유로 자주 언급됩니다. 런타임 마찰, 시크릿 관리, 다대다 연결 문제를 컨테이너+게이트웨이로 줄일 수 있다는 논리죠.³

Agent-shell을 쓴다면 추천 흐름은 이렇습니다. “Emacs는 호스트에서 편하게 쓰고, 에이전트 프로세스/도구(MCP)는 컨테이너로 격리한다.” 이렇게 역할을 나누면, 키보드 생산성은 유지하면서 리스크를 크게 낮출 수 있습니다.

시사점: Agent-shell은 ‘Emacs에 에이전트 문화’가 들어오는 방식이다

Agent-shell의 핵심 가치는 화려한 UI가 아니라, Emacs의 버퍼/프로세스 철학 위에 ACP라는 표준을 얹었다는 점입니다. ACP 덕분에 에이전트를 바꿔도 인터페이스가 유지되고, MCP 같은 도구 레이어를 붙이면 “에이전트-툴-에디터”가 깔끔하게 분리됩니다.¹³

처음에는 MELPA 설치와 환경 변수 설정이 번거롭게 느껴질 수 있습니다. 하지만 한 번 자리를 잡아두면, Emacs 안에서 에이전트를 ‘상시 대기’시키고 필요할 때 호출하는 흐름이 생각보다 중독적이에요. 키보드에서 손을 떼지 않고도 설계, 구현, 문서화, 점검을 한 공간에서 끝낼 수 있으니까요.

다음 단계로는 “나만의 디폴트 에이전트 + 프로젝트별 MCP 도구 세트”를 템플릿처럼 만들어보세요. 그 순간부터 Agent-shell은 채팅 도구가 아니라, 진짜 개발 환경의 일부가 됩니다.