애플리케이션이 충돌했습니다.

터미널에는 47줄의 빨간색 텍스트, 이해할 수 없는 세 개의 경고, 그리고 유난히 '도움이 되는' 메시지 하나가 나타났습니다.

Something went wrong.

이 내용을 브라우저 탭 다섯 개에 나누어 붙여넣을 수도 있습니다.

아니면 에러를 설명해주고, 다음에 무엇을 확인해야 할지 제안하며, 명령 출력(command output)을 인내심 있게 기다려주는 텔레그램 봇에게 보낼 수도 있습니다.

이 튜토리얼에서는 바로 그것을 만들어 볼 것입니다.

Debug Duck 🦆을 소개합니다: 텔레그램에 상주하며 스택 트레이스(stack traces), 로그(logs), 그리고 정체불명의 서버 에러를 해결하도록 도와주는 개인용 AI 어시스턴트입니다.

일반적인 러버 덕(rubber duck)과 달리, 이 녀석은 대답을 합니다.

가끔은 꽤 유용할지도 모릅니다.

🦆 우리가 만들 것

설정은 간단합니다:

사용자
 ↓
Telegram
...

사용자는 봇에게 에러, 로그 조각, 명령 출력, 또는 스택 트레이스를 보냅니다.

OpenClaw가 시스템 프롬프트(system prompt)와 대화 기록(conversation history)을 추가하고, 선택한 언어 모델(language model)로 요청을 보낸 뒤, 답변을 텔레그램으로 반환합니다.

가이드를 마칠 때쯤, 여러분의 봇은 다음과 같은 능력을 갖추게 됩니다:

• 에러를 쉬운 영어로 설명하기;
• 확인된 사실과 가능성 있는 원인을 분리하기;
• 몇 가지 진단 단계 제안하기;
• 실행 가능한 명령 제공하기;
• 다음 확인 결과 요청하기;
• 현재 디버깅 컨텍스트(debugging context) 기억하기.

이 봇이 자동으로 서버에 로그인하여 모든 것을 고쳐주지는 않습니다.

그 기능은 흔히 "AI 에이전트에게 루트 권한(root access)을 주고 인격적 성장을 기대하는 것"이라고 불리기도 합니다.

준비물

다음 사항들을 준비하세요:

• Ubuntu가 실행 중인 Linux VPS;
• Telegram 계정;
• 지원되는 언어 모델의 API 키;
• 약 20~30분 정도의 시간;
• 이미 여러분의 하루를 망쳐버린 에러 메시지 하나.

OpenClaw 자체는 외부 모델 API를 사용할 때 매우 가볍습니다.

개인용 봇을 위해서는 다음과 같은 사양의 작은 VPS만으로도 충분합니다:

이 튜토리얼은 Serverspace VPS를 사용하지만, OpenClaw 및 Telegram 단계는 일반적인 Ubuntu 서버에서도 동일합니다.

1단계: 작은 Linux VPS 생성하기

Ubuntu 서버를 생성하고 SSH를 통해 연결합니다:

ssh root@YOUR_SERVER_IP

YOUR_SERVER_IP를 VPS의 공인 IP 주소로 바꿉니다.

설치된 패키지를 업데이트합니다:

apt update && apt upgrade -y

언어 모델 (Language model) 자체는 외부 API를 통해 실행되므로, VPS는 주로 다음 사항을 처리합니다:

• Telegram 메시지;
• OpenClaw 게이트웨이 (gateway);
• 설정 (configuration);
• 대화 기록 (conversation history).

Ollama를 사용한 로컬 추론 (Local inference)은 이야기가 다릅니다.

RAM이 1GB인 서버는 7B 모델을 보고 조용히 한숨을 내쉬며 참여를 거부할 것입니다.

2단계: OpenClaw 설치하기

공식 설치 프로그램을 실행합니다:

curl -fsSL https://openclaw.ai/install.sh | bash

설치 프로그램이 운영 체제를 감지하고, 필요한 종속성 (dependencies)을 설치하며, 온보딩 (onboarding) 프로세스를 시작합니다.

OpenClaw는 Node.js 22.14 이상이 필요합니다. Node.js 24를 권장합니다.

온보딩 과정 중:

1. 사용할 언어 모델 제공업체를 선택합니다.
2. 제공업체의 API 키를 입력합니다.
3. 기본적인 어시스턴트 설정을 완료합니다.
4. 안내에 따라 백그라운드 서비스 (background service)를 활성화합니다.

설치 후, OpenClaw CLI를 사용할 수 있는지 확인합니다:

openclaw --version

내장된 진단 도구를 실행합니다:

openclaw doctor

그 다음 게이트웨이 상태를 확인합니다:

openclaw gateway status

openclaw doctor가 심각한 문제가 없다고 보고하면, 러버 덕은 살아있는 것입니다.

단지 아직 Telegram 계정이 없을 뿐입니다.

3단계: Telegram 봇 만들기

Telegram을 열고 공식 @botfather 계정을 찾습니다.

다음 명령어를 보냅니다:

/newbot

BotFather가 다음 사항을 요청할 것입니다:

1. 표시 이름 (display name);
2. bot으로 끝나는 사용자 이름 (username).

예시:

표시 이름: Debug Duck
사용자 이름: debug_duck_bot

봇이 생성되면, BotFather는 다음과 같이 보이는 토큰을 제공합니다:

123456789:AAExampleTokenThatShouldRemainSecret

이 토큰을 비밀번호처럼 취급하세요.

긴급한 토큰 교체 (token rotation) 상황을 즐기는 것이 아니라면, 이 토큰을 공개 GitHub 저장소에 붙여넣지 마세요.

Step 4: Telegram을 OpenClaw에 연결하기

OpenClaw 설정 파일을 엽니다:

nano ~/.openclaw/openclaw.json

Telegram 채널을 추가합니다:

{
  "channels": {
    "telegram": {
...

YOUR_TELEGRAM_BOT_TOKEN을 BotFather로부터 받은 토큰으로 교체합니다.

파일을 저장하고 Nano를 종료합니다:

Ctrl + O
Enter
Ctrl + X

여기서 중요한 옵션은 다음과 같습니다:

"dmPolicy": "pairing"

Pairing (페어링)은 봇의 사용자 이름을 찾는 것만으로는 사용을 시작하기에 충분하지 않음을 의미합니다. 새로운 사용자는 먼저 승인을 받아야 합니다.

이는 무작위의 낯선 사람이 당신의 봇을 발견하고, 12권 분량의 판타지 시리즈를 써달라고 요청하며 당신의 API 예산을 낭비하는 것을 방지합니다.

개인용 봇의 경우, 제한 없는 접근을 허용하는 개방형 다이렉트 메시지 (direct-message) 정책은 피하세요.

Step 5: Debug Duck으로 만들기

일반적인 AI 어시스턴트는 거의 무엇이든 답변할 것입니다.

그것은 스택 트레이스 (stack trace)를 보냈을 때 소프트웨어 품질의 중요성에 대한 다섯 문단짜리 에세이를 돌려받기 전까지는 유용하게 들릴 것입니다.

우리는 어시스턴트에게 훨씬 더 명확한 직무를 부여해야 합니다.

OpenClaw 온보딩 (onboarding) 중에 생성된 어시스턴트 또는 에이전트 설정을 통해 다음 시스템 프롬프트 (system prompt)를 추가하세요:

You are Debug Duck, a patient debugging assistant for beginner developers.

When the user sends an error message, stack trace, log fragment, command output, or code:
...

다음과 같은 프롬프트는 피하세요:

You are a helpful assistant.

이것은 모델에게 다음과 같은 수준의 지침만을 주는 것과 같습니다:

그냥 운영 환경(production)을 고쳐줘.

역할, 규칙, 응답 형식이 구체적일수록 어시스턴트는 더욱 예측 가능해집니다.

Step 6: 게이트웨이 시작하기

OpenClaw 게이트웨이를 시작합니다:

openclaw gateway

이제 Telegram에서 새로운 봇을 열고 메시지를 보내보세요:

Hello

페어링 (pairing)을 활성화했기 때문에, 봇이 대화를 즉시 수락해서는 안 됩니다.

서버로 돌아가서 대기 중인 Telegram 페어링 요청을 확인하세요:

openclaw pairing list telegram

표시된 코드를 승인합니다:

openclaw pairing approve telegram YOUR_PAIRING_CODE

YOUR_PAIRING_CODE를 OpenClaw에 표시된 실제 코드로 교체하세요.

페어링 코드는 한 시간 동안 유효합니다.

이제 Telegram 메시지를 하나 더 보내보세요:

Are you alive?

좋은 답변은 다음과 같을 것입니다:

Yes. Send me an error message, stack trace, or command output, and I’ll help you work through it.

덜 유용한 답변은 소프트웨어가 진정으로 살아있을 수 있는지에 대한 실존적 토론일 것입니다.

그럴 경우 시스템 프롬프트 (system prompt)를 다시 살펴봐야 할 수도 있습니다.

7단계: 러버 덕에게 디버깅할 거리 주기

몇 가지 흔한 에러로 봇을 테스트해 봅시다.

테스트 1: Port 80이 이미 사용 중인 경우

봇에게 다음 에러를 보내세요:

nginx: [emerg] bind() to 0.0.0.0:80 failed
(98: Address already in use)

Debug Duck은 다른 프로세스가 이미 80번 포트에서 리스닝 (listening) 중임을 설명하고, 다음과 같은 진단 명령어를 제안해야 합니다:

sudo lsof -i :80

좋은 답변은 다음과 같은 모습일 것입니다:

Port 80 is already occupied. Nginx is trying to sit in a chair that someone else has taken.

Check which process is using the port:
...

농담은 한 문장이면 충분합니다.

진단 단계가 핵심입니다.

테스트 2: Node.js 의존성 (dependency)이 누락된 경우

다음 내용을 보내세요:

Error: Cannot find module 'express'

어시스턴트는 현재 환경에 해당 의존성이 누락되었음을 설명하고, 프로젝트 디렉토리와 설치된 패키지를 확인하도록 제안해야 합니다:

pwd
npm list express

다음과 같은 조치를 즉시 권장해서는 안 됩니다:

• node_modules 삭제
• 사용 가능한 모든 캐시(cache) 삭제
• Node.js 재설치
• 락 파일 (lock file) 희생

훌륭한 디버깅은 실제로 무슨 일이 일어나고 있는지 확인하는 것에서 시작됩니다.

테스트 3: 서버 공간이 부족한 경우

보내기:

No space left on device

봇은 다음과 같은 안전한 진단 명령어로 시작해야 합니다:

df -h

그 다음, 어떤 최상위 디렉토리가 디스크 공간을 가장 많이 차지하는지 확인하도록 제안할 수 있습니다:

du -xhd1 / 2>/dev/null | sort -h

봇은 삭제를 제안하기 전에 경고를 주어야 합니다.

"디스크 가득 참"은 진단입니다.

"서버가 부팅될 때까지 무작위로 무언가를 삭제하기"는 라이프스타일의 선택입니다.

8단계: 답변의 품질 확인하기

목표는 단순히 봇이 응답하게 만드는 것이 아닙니다.

유용한 디버깅 어시스턴트(debugging assistant)라면 다음과 같이 해야 합니다:

• 에러가 무엇을 의미하는지 설명합니다.
• 추측을 사실인 것처럼 가장하는 것을 피합니다.
• 소수의 확인 사항을 제안합니다.
• 각 명령어가 무엇을 하는지 설명합니다.
• 추가 정보를 기다립니다.
• 위험한 행동을 하기 전에 경고합니다.

예를 들어, 다음과 같은 답변은 좋은 답변이 아닙:

Nginx를 재설치하고 서버를 재시작하세요.

어시스턴트는 다음 사항들을 확인하지 않았습니다:

• 어떤 프로세스가 80번 포트를 점유하고 있는지;
• Nginx가 이미 실행 중인지;
• Apache가 설치되어 있는지;
• 컨테이너가 해당 포트를 게시(publish)했는지.

더 나은 답변은 진단에서 시작합니다.

Debug Duck은 점심시간 전에 티켓을 닫으려는 사람처럼 행동하는 것이 아니라, 인내심 있는 팀원처럼 행동해야 합니다.

9단계: 봇을 비공개로 유지하기

봇은 유료 언어 모델 API에 접근할 수 있으므로, 접근 제어(access control)가 중요합니다.

개인용 어시스턴트라면 페어링 정책(pairing policy)을 활성화된 상태로 유지하세요.

다음과 같은 설정은 피해야 합니다:

{
  "dmPolicy": "open",
  "allowFrom": ["*"]
...

이 설정은 사용자 이름을 발견한 누구라도 봇을 사용할 수 있게 합니다.

또한 로그와 스택 트레이스(stack traces)를 외부 언어 모델로 보내기 전에 검토해야 합니다.

로그에는 다음과 같은 내용이 포함되어 있을 수 있습니다:

• API 키;
• 액세스 토큰(access tokens);
• 내부 호스트 이름;
• 데이터베이스 주소;
• 이메일 주소;
• 사용자 데이터의 파편;
• 개인 파일 경로.

Debug Duck은 에러를 조사하기 위해 존재하는 것이지, 당신의 인프라 지도를 몰래 수집하기 위해 존재하는 것이 아닙니다.

10단계: Git에 비밀 정보 노출하지 않기

텔레그램 토큰이나 모델 제공자 토큰을 공개 저장소(public repository)에 절대 저장하지 마세요.

최소한:

1. 비밀 정보(secrets)를 환경 변수(environment variables) 또는 보호된 설정 파일(protected configuration file)에 저장하세요.
2. 로컬 비밀 파일들을 .gitignore에 추가하세요.
3. 설정 파일에 대한 권한(permissions)을 제한하세요.
4. 토큰이 공개되면 즉시 교체(rotate)하세요.

OpenClaw 설정 파일에 대한 액세스를 제한하세요:

chmod 600 ~/.openclaw/openclaw.json

실수로 GitHub에 토큰을 푸시(push)했다면, 최신 커밋(commit)에서 이를 제거하는 것만으로는 충분하지 않습니다.

토큰이 저장소 기록(repository history)에 여전히 남아 있을 수 있기 때문입니다.

해당 토큰을 무효화(revoke)하고 새 토큰을 생성하세요.

인터넷은 당신이 유출된 비밀 정보를 발견하기 약 4초 전에 이를 찾아내는 놀라운 능력을 가지고 있습니다.

11단계: 대화 기록(Conversation History) 제어하기

OpenClaw는 대화 문맥(conversation context)을 유지할 수 있습니다.

이를 통해 봇이 디버깅 세션을 따라갈 수 있게 합니다:

1. 당신이 Nginx 에러를 보냅니다.
2. 봇이 어떤 프로세스가 80번 포트를 사용 중인지 묻습니다.
3. 당신이 명령어 출력 결과(command output)를 보냅니다.
4. 봇은 이것이 동일한 문제에 속해 있음을 이해합니다.

하지만 대화 기록이 길어지면 이전 메시지들이 이후의 요청(requests)에 포함될 수 있으므로 API 비용이 증가할 수 있습니다.

디버깅 어시스턴트의 경우, 보통 10~20회 정도의 메시지 교환을 유지하는 것으로 충분합니다.

Nginx와의 관계에 대한 전체 감정적 역사를 보관할 필요는 거의 없습니다.

사용 중인 버전에서 지원하는 OpenClaw 설정에서 적절한 기록 제한(history limit)을 설정하세요.

12단계: 재부팅 후에도 유지되도록 하기

서버가 재시작될 때마다 사라지는 디버깅 봇은 또 다른 디버깅 문제를 야기합니다.

OpenClaw 게이트웨이(gateway)를 백그라운드 서비스(background service)로 설치하세요:

openclaw gateway install

온보딩(onboarding) 과정 중에 설치할 수도 있습니다:

openclaw onboard --install-daemon

Linux에서 OpenClaw는 systemd 사용자 서비스(user service)를 구성합니다.

게이트웨이 상태를 확인하세요:

openclaw gateway status

만약 봇이 응답을 멈춘다면, 다음 명령어로 시작하세요:

openclaw doctor
openclaw gateway status
openclaw logs --follow

이 명령어들은 문제가 무엇인지 판단하는 데 도움이 될 수 있습니다:

• OpenClaw 프로세스;
• Telegram 연결;
• 유효하지 않은 프로바이더 (provider) API 키;
• 소진된 API 잔액;
• 설정 (configuration) 오류.

네, 결국 당신은 디버깅을 위한 봇을 디버깅해야 할 수도 있습니다.

모든 도구는 충분히 오래 의존하게 되면 인프라 (infrastructure)가 됩니다.

당신의 스택에 더 유용한 봇 만들기

기본 버전이 작동하기 시작하면, 당신이 가장 자주 사용하는 기술에 맞춰 시스템 프롬프트 (system prompt)를 조정하세요.

예를 들어:

사용자는 주로 다음을 사용합니다:

- Ubuntu
...

또한 고정된 응답 형식을 요구할 수도 있습니다:

에러의 의미

확인된 사항
...

예측 가능한 형식은 휴대폰에서 답변을 훑어보기에 더 쉽게 만듭니다.

봇의 특화된 버전을 만들 수도 있습니다.

커밋 메시지 테라피스트 (Commit Message Therapist)

변경 사항에 대한 설명을 보내면 다음과 같은 것보다 훨씬 나은 결과를 받을 수 있습니다:

fix stuff final final

스탠드업 고블린 (Standup Goblin)

어제의 혼란스러운 메모를 보내면 다음과 같은 결과를 얻을 수 있습니다: