AI 코딩 도구를 쓰다가 갑자기 멈춰버린 경험, 있으신가요?

요즘 AI 코딩 에이전트에 관심을 가지는 분들이 정말 많아졌습니다. Claude Code의 오픈소스 대안인 OpenClaw를 설치하고, 비용 절감을 위해 Google의 Gemini 2.5 Pro 모델을 연결해서 쓰시는 분들도 늘어나고 있습니다. 그런데 막상 사용해 보면 "왜 갑자기 도구가 작동을 안 하지?", "왜 AI가 코드를 실행하지 않고 텍스트로만 출력하지?" 같은 당황스러운 상황을 겪게 되는 경우가 많습니다.

이 글에서는 OpenClaw에서 Gemini 2.5 Pro(및 후속 Gemini 3 모델)를 연동할 때 실제로 발생하는 대표적인 버그들을 쉽게 풀어서 설명해 드리겠습니다. 기술적인 배경지식이 없어도 이해할 수 있도록, 비유와 실제 사례를 중심으로 정리했습니다.

왜 이 문제가 중요한가요?

OpenClaw 같은 AI 코딩 에이전트의 핵심 기능은 **도구 호출(tool call)**입니다. 쉽게 말해, AI가 단순히 "이렇게 하세요"라고 말하는 것이 아니라, 직접 파일을 읽고, 코드를 수정하고, 명령어를 실행하는 것입니다. 마치 요리사가 레시피를 읽어주기만 하는 것이 아니라, 직접 칼을 들고 재료를 썰어주는 것과 같습니다.

Gemini 모델을 연동했을 때 이 도구 호출이 제대로 작동하지 않으면, AI 에이전트는 사실상 "말만 하는 조수"가 되어버립니다. 파일을 수정하라고 했는데 수정 방법만 텍스트로 알려주거나, 아예 응답이 멈춰버리는 상황이 발생합니다.

비용을 아끼려고 Gemini를 선택한 분들에게 이런 불안정성은 오히려 시간과 에너지를 더 소모하게 만들 수 있습니다. 그래서 어떤 문제가 있는지 미리 알고, 대처 방법을 준비하는 것이 중요합니다.

대표적인 버그 3가지

버그 1: AI가 도구를 실행하지 않고 텍스트로 출력하는 문제

GitHub Issue #3344 — 가장 많이 보고되는 문제입니다.

정상적인 상황이라면, "이 파일을 읽어줘"라고 요청하면 AI가 실제로 read 도구를 호출해서 파일 내용을 보여줍니다. 하지만 Gemini 모델에서는 도구를 실행하는 대신, 마치 연극 대본처럼 "도구를 호출했습니다"라는 텍스트를 출력하는 경우가 있습니다.

실제로 사용자들이 보고한 증상은 다음과 같습니다:

• AI가 [Historical context: a different model called tool "read" with arguments...] 같은 이상한 텍스트를 출력합니다
• 도구가 실행되지 않았으므로, 실제 파일 내용은 볼 수 없습니다
• 로그를 확인하면 stopReason이 "tool_use"가 아닌 "stop"으로 표시됩니다

비유하자면, 택배 기사에게 물건을 배달해달라고 했는데, 배달하는 척만 하고 "배달했습니다"라고 문자만 보내는 것과 비슷합니다.

원인: Gemini 모델이 Claude와는 다른 방식으로 도구 호출을 처리하기 때문입니다. Claude는 XML 스타일의 tool_use 블록을 사용하지만, Gemini는 function_call 방식을 사용합니다. OpenClaw의 메시지 변환 과정에서 이 차이가 제대로 처리되지 않으면, Gemini가 도구 호출 형식을 "흉내"만 내는 현상이 발생합니다.

버그 2: thoughtSignature 검증 실패 오류

GitHub Issue #5001 — 대화가 길어지면 발생하는 문제입니다.

Gemini 모델(특히 Gemini 3 계열)은 도구 호출 응답에 thoughtSignature라는 메타데이터(부가 정보)를 붙입니다. 이것은 일종의 "디지털 서명"으로, AI의 사고 과정을 검증하기 위한 것입니다.

문제는 OpenClaw가 이 서명을 대화 기록에 포함해서 다시 Gemini에게 보낼 때 발생합니다. Google의 API가 "이 서명은 유효하지 않습니다"라는 오류를 반환하면서 대화가 중단됩니다.

구체적인 증상은 다음과 같습니다:

• 첫 번째 도구 호출은 정상적으로 작동합니다
• 두 번째 이후의 도구 호출에서 "Thought signature is not valid" 에러가 발생합니다
• 대화가 완전히 멈추고, 새 대화를 시작해야만 해결됩니다

비유하자면, 공항 보안 검색대를 통과할 때 첫 번째 검문에서 받은 도장이 두 번째 검문에서는 인식되지 않는 것과 같습니다.

원인: OpenClaw가 대화 기록을 API에 전송할 때 thoughtSignature 필드를 제거하지 않아서 발생합니다. Gemini 3에서는 이 필드의 검증이 필수가 되었지만, 한번 사용된 서명은 재검증이 불가능합니다.

버그 3: 모델 전환 후 도구 호출 멈춤

GitHub Issue #13461 — 모델을 전환하는 분들이 겪는 문제입니다.

OpenClaw에서는 대화 중간에 모델을 바꿀 수 있습니다. 예를 들어, Claude로 시작했다가 비용 절감을 위해 Gemini로 전환하는 경우입니다. 하지만 이때 이전 Claude 세션에서 생성된 도구 호출 기록이 Gemini에게 전달되면, Gemini가 혼란을 일으킵니다.

증상은 다음과 같습니다:

• Claude에서 Gemini로 전환한 후, 도구 호출을 요청하면 AI가 멈춥니다
• 대화 기록 중 서명되지 않은 도구 호출 기록을 Gemini가 텍스트로 "복제"합니다
• 약 200K 토큰 이상의 큰 컨텍스트에서 특히 심각합니다

원인: OpenClaw의 Google 어댑터가 서명되지 않은 도구 호출을 발견하면, 이를 설명하는 안내 텍스트(shim)를 생성합니다. 문제는 이 안내 텍스트의 형식이 너무 "따라하기 쉬운" 형태여서, Gemini가 도구를 실행하는 대신 이 텍스트를 그대로 복제해버립니다.

긴 대화에서의 불안정성 문제

위의 세 가지 버그 외에도, Gemini 2.5 Pro는 긴 대화에서 전반적으로 불안정해지는 경향이 있습니다. Google AI 개발자 포럼에서도 많은 개발자들이 이 문제를 보고하고 있습니다.

주요 증상들은 다음과 같습니다:

• 100개 이상의 메시지: 컨텍스트 윈도우(대화 기억 용량)가 9~12K 토큰을 넘어가면 도구 호출이 불안정해집니다
• 무한 루프: 간단한 작업을 위해 불필요한 도구 호출을 반복하면서 API 비용만 증가합니다
• 빈 응답: 아무런 응답 없이 세션이 종료되거나, 500 에러가 반환됩니다
• 프리뷰 vs 정식 버전 역전: 놀랍게도 프리뷰(실험) 버전이 정식 버전보다 더 안정적인 경우가 있습니다

이런 문제들은 Gemini 2.5 Pro의 근본적인 한계와도 관련이 있습니다. Google이 비용 효율을 위해 모델을 "증류(distill)"하는 과정에서 성능이 저하되었을 가능성이 제기되고 있습니다.

실용적인 대처 방법

이런 문제들이 있다고 해서 Gemini를 아예 쓸 수 없는 것은 아닙니다. 다음과 같은 방법으로 문제를 줄일 수 있습니다.

즉시 적용 가능한 해결책

1. 새 대화 시작하기: 문제가 발생하면 /new 또는 /reset 명령어로 새 세션을 시작하세요. 대부분의 도구 호출 문제가 해결됩니다.
2. 모델 전환 피하기: 한 세션 내에서 Claude와 Gemini를 섞어 쓰지 마세요. 한 세션에는 하나의 모델만 사용하는 것이 안정적입니다.
3. 대화 길이 관리하기: 대화가 너무 길어지기 전에 주기적으로 새 세션을 시작하세요. 50~70개 메시지 정도가 안전한 범위입니다.
4. 최신 버전 유지하기: OpenClaw의 업데이트에는 이런 호환성 문제에 대한 수정이 포함되는 경우가 많습니다.

모델 선택 가이드

• 안정성이 중요한 작업: Claude 모델을 사용하세요. 도구 호출 안정성이 가장 높습니다.
• 간단한 질의응답: Gemini도 충분히 잘 작동합니다. 도구 호출이 필요 없는 대화에서는 문제가 거의 없습니다.
• 비용과 안정성의 균형: 핵심 작업은 Claude로, 보조적인 작업은 Gemini로 나누어 사용하는 전략이 효과적입니다.

시작하기: 더 안정적인 AI 에이전트 환경

만약 이런 기술적인 호환성 문제를 직접 해결하기 어렵다면, 몇 가지 대안이 있습니다.

가장 간단한 방법은 Claude 모델을 기본으로 사용하는 것입니다. OpenClaw는 원래 Claude Code를 기반으로 만들어진 프로젝트이므로, Claude 모델과의 호환성이 가장 좋습니다.

설치 과정 자체가 부담스러우신 분들은 EasyClaw 같은 클라우드 기반 서비스를 고려해 보실 수 있습니다. 복잡한 설치 없이 브라우저에서 바로 OpenClaw를 사용할 수 있고, 모델 호환성 문제도 사전에 검증된 설정으로 제공되기 때문에 초보자분들에게 특히 편리합니다.

마무리

OpenClaw에서 Gemini 2.5 Pro를 연동하는 것은 비용 절감이라는 매력적인 장점이 있지만, 현재 시점에서는 도구 호출 관련 버그들이 완전히 해결되지 않은 상태입니다. 이 글에서 소개한 세 가지 핵심 버그(가짜 도구 호출, thoughtSignature 검증 실패, 모델 전환 멈춤)를 미리 알고 대비하시면, 훨씬 안정적으로 AI 코딩 에이전트를 활용하실 수 있습니다. 기술은 계속 발전하고 있으니, 지금은 안정적인 환경에서 시작하시고 점차 다양한 모델을 시도해 보시는 것을 추천드립니다.