대화형 예산 — 핵심 파이프라인

Telegram을 통해 자연어로 지출을 기록하는 시스템으로, Google Gemini(공식 API, .env에서 모델 설정 가능, 기본값 gemini-3.6-flash)를 언어 모델로 사용하며, Nanobot이 오케스트레이션하고 데이터는 Postgres에 저장됩니다.

이 문서는 Docker를 한 번도 실행해 본 적 없는 사용자를 가정하며, 각 단계, 각 명령어, 그리고 각 단계의 예상 결과를 설명합니다.

목차

1. 설치해야 할 것

2. Telegram에서 봇 토큰 얻기

3. Gemini API 키 얻기

4. .env 파일 설정

5. Docker로 모두 실행하기

6. Telegram에서 테스트

7. 일상적인 명령어

8. 일반적인 문제와 해결 방법

9. 프로젝트의 각 파일이 하는 일

10. 대안: 로컬 설치(Docker 없이)

11. 프로젝트의 다음 단계

Related MCP server: Expense Tracker MCP Server

1. 설치해야 할 것

여러분의 컴퓨터에 필요한 것은 단 하나입니다. Python, Postgres 또는 Nanobot을 별도로 설치할 필요가 없습니다 — 모든 것이 컨테이너 안에서 실행됩니다.

Docker Desktop(Windows/Mac) 또는 Docker Engine(Linux)

• Windows 또는 Mac: https://www.docker.com/products/docker-desktop/ 에서 Docker Desktop을 다운로드하여 설치합니다. 설치 후 Docker Desktop 애플리케이션을 열고 "Docker is running"이 표시될 때까지 기다립니다(시스템 트레이에서 아이콘이 녹색/안정적으로 표시됨).

• Linux: 해당 배포판에 맞는 https://docs.docker.com/engine/install/ 을 따르고, sudo 없이 docker를 실행하려면 https://docs.docker.com/engine/install/linux-postinstall/ 도 따릅니다.

모든 것이 제대로 되었는지 확인

터미널(Windows의 PowerShell, Mac/Linux의 Terminal)을 열고 다음을 실행합니다:

docker --version
docker compose version

오류 없이 두 줄의 버전이 표시되어야 합니다.

2. Telegram에서 봇 토큰 얻기

1. Telegram(휴대폰 또는 데스크톱)을 열고 검색에서 @BotFather를 찾습니다. 봇을 만드는 공식 Telegram 봇입니다. 인증된 배지가 있는지 확인하세요.

2. 그에게 /newbot을 보냅니다.

3. 봇의 이름을 묻습니다. 아무 이름이나 가능합니다. 예: 대화형 예산.

4. 그다음 사용자 이름을 묻습니다. 이 이름은 Telegram 전체에서 고유해야 하며 "bot"으로 끝나야 합니다. 예: orcamento_seunome_bot.

5. 성공하면 BotFather가 다음과 같은 메시지로 응답합니다:

   Done! Congratulations on your new bot. You will find it at
   t.me/orcamento_seunome_bot. You can now add a description...
   
   Use this token to access the HTTP API:
   7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   
   Keep your token secure and store it safely...

6. 토큰 줄 전체를 복사합니다(형식은 숫자:문자_및_숫자). 다음 단계에서 .env 파일에 붙여넣습니다.

이 토큰을 보관하세요.

3. Gemini API 키 얻기

Nanobot은 언어 모델로 Google Gemini 공식 API를 사용합니다.

1. https://aistudio.google.com/api-keys 에 접속하여 Google 계정으로 로그인합니다.

2. Create API key를 클릭합니다(Google이 자동으로 프로젝트를 생성합니다).

3. 키를 복사하여 다음 단계에서 .env에 붙여넣습니다.

비용에 관해: 카드를 요구하지 않습니다. 무료 티어는 Flash/Flash-Lite 모델을 분당/일당 요청 한도(모델에 따라 ~10 req/min 및 ~250–1,500 req/day)로 지원합니다 — 이 프로젝트에는 충분합니다. Pro 모델은 유료입니다. 공식 표: https://ai.google.dev/gemini-api/docs/pricing

4. .env 파일 설정

프로젝트에는 이미 폴더 루트(orcamento-conversacional/.env)에 .env 파일이 있습니다. Docker Compose가 자동으로 읽으므로 이름을 바꿀 필요가 없습니다.

주의: 점으로 시작하는 파일(.env)은 Windows 파일 탐색기, Mac Finder, Linux/Mac의 플래그 없는 ls에서 기본적으로 "숨김"입니다. 터미널에서 보려면 ls -la를 사용하거나 텍스트 편집기로 폴더를 여세요.

.env 안에서 다음 두 줄을 실제 값으로 바꿉니다:

TELEGRAM_TOKEN=coloque_seu_token_aqui      ← token do BotFather (seção 2)
GEMINI_API_KEY=coloque_sua_chave_aqui      ← chave do AI Studio (seção 3)

GEMINI_MODEL 변수는 사용할 모델을 정의합니다(기본값: gemini-3.6-flash). 공식 목록의 다른 유효한 ID로 바꾸려는 경우에만 수정하세요: https://ai.google.dev/gemini-api/docs/models

다른 변수(POSTGRES_PASSWORD, DATABASE_URL)는 이미 작동하는 값이 들어 있습니다 — Docker에서 실행할 때는 건드릴 필요가 없습니다.

파일을 저장합니다.

5. Docker로 모두 실행하기

docker-compose.yml 파일이 있는 orcamento-conversacional 폴더 안에서 터미널을 열고 다음을 실행합니다:

docker compose up -d --build

이 명령이 하는 일을 순서대로:

모델을 다운로드하거나 실행하지 않습니다. Gemini는 Google 클라우드에서 실행됩니다.

-d("detached") 플래그는 모든 것을 백그라운드에서 실행합니다. 다음에 docker compose up -d(--build 없이)를 실행하면 몇 초 만에 시작됩니다.

모든 것이 제대로 되었는지 확인하는 방법

다음을 실행합니다:

docker compose ps

2개의 서비스가 보여야 합니다:

NAME                    IMAGE                    STATUS
orcamento_postgres      postgres:16-alpine       Up (healthy)
orcamento_nanobot       ...nanobot               Up

Nanobot 로그도 확인하세요 — MCP가 연결된 것으로 표시되어야 합니다:

docker compose logs nanobot

다음과 같은 줄을 찾으세요:

MCP: registered tool 'mcp_orcamento_registrar_despesa' from server 'orcamento'
MCP server 'orcamento': connected, 3 capabilities registered
✓ Health endpoint: http://127.0.0.1:18790/health
bot @seubot connected

orcamento_nanobot이 "Restarting"으로 표시되거나 목록에서 사라지면 일반적인 문제 섹션을 참조하세요.

6. Telegram에서 테스트

1. Telegram에서 BotFather로 만든 봇의 사용자 이름(예: @orcamento_seunome_bot)을 검색하고 대화를 시작합니다.

2. /start를 보냅니다. 첫 대화에서 Nanobot이 페어링 코드를 요청할 수 있습니다 — 로그에 표시됩니다(docker compose logs -f nanobot, "Generated pairing code ..." 줄). 이 코드를 봇에게 보냅니다.

3. 다음과 같이 보냅니다:

   Gastei 35 no almoço hoje

4. 몇 초 안에 봇이 등록을 확인하는 응답을 보내야 합니다. 예:

   Registrado: R$ 35,00 em alimentação (almoço).

봇이 아무 응답도 하지 않으면 아래 일반적인 문제 섹션을 참조하세요.

7. 일상적인 명령어

모두 orcamento-conversacional 폴더 안에서 실행합니다.

모든 로그를 실시간으로 보기:

docker compose logs -f

(Ctrl+C로 종료 — 로그 표시만 중지되며 컨테이너는 계속 실행됩니다.)

Nanobot 로그만 보기(대화 디버깅에 가장 유용):

docker compose logs -f nanobot

모두 중지(데이터는 유지):

docker compose down

중지 후 다시 시작:

docker compose up -d

SOUL.md, config.docker.json 또는 .env를 편집한 후 (이미지를 다시 빌드할 필요 없음; 구성과 프롬프트는 컨테이너에 직접 마운트됨):

docker compose up -d nanobot    # recria o container aplicando o novo .env

mcp_server/expense_tools.py 또는 db/connection.py를 편집한 후 (MCP venv가 이미지에 생성되므로 다시 빌드해야 함):

docker compose up -d --build nanobot

데이터베이스 데이터를 포함한 모든 것을 완전히 삭제 (무언가 손상되어 처음부터 다시 시작하려는 경우 유용):

docker compose down -v

데이터베이스에 들어가 등록된 지출을 수동으로 확인:

docker exec -it orcamento_postgres psql -U orcamento -d orcamento

psql 안에서 다음을 시도해 보세요:

SELECT * FROM despesas ORDER BY criado_em DESC LIMIT 10;

psql에서 나가려면 \q를 입력하고 Enter를 누릅니다.

선택적 단축키: make가 설치되어 있으면(Mac/Linux 기본), 프로젝트에는 가장 많이 사용되는 명령이 포함된 Makefile이 있습니다: make up, make down, make logs, make restart, make ps.

8. 일반적인 문제와 해결 방법

Error: Environment variable 'GEMINI_API_KEY' referenced in config is not set

.env에 GEMINI_API_KEY 변수가 정의되어 있지 않습니다. .env를 열고 해당 줄이 있는지 확인하고(임시 값이라도) docker compose up -d nanobot을 다시 실행하세요.

Nanobot 로그의 401, unauthorized 또는 invalid api key

GEMINI_API_KEY가 잘못되었거나, 취소되었거나, 추가 공백이 있습니다. https://aistudio.google.com/api-keys 에서 새 키를 생성하고 .env를 업데이트하세요.

429 또는 rate limit / quota 오류

Gemini 무료 티어 한도(분당 또는 일당 요청)에 도달했습니다. 옵션: 몇 분 기다리기, .env의 GEMINI_MODEL을 Flash-Lite 모델(한도가 더 높음, 예: gemini-3.1-flash-lite)로 변경하고 다시 시작, 또는 Google Cloud 계정에서 결제를 활성화.

로그의 model not found

GEMINI_MODEL 값이 Gemini API의 유효한 ID가 아닙니다. https://ai.google.dev/gemini-api/docs/models 의 공식 목록을 확인하고 .env를 수정하세요.

봇이 tools를 호출하지 않거나 등록할 수 없다고 말함

docker compose logs nanobot을 실행하고 다음을 찾으세요:

• MCP server 'orcamento': connected — 나타나지 않으면 내장 MCP 서버 시작에 실패한 것입니다. 해당 줄 바로 위의 오류를 확인하세요.

• Max iterations (...) reached — 모델이 tool-call 루프에 빠졌다는 뜻입니다. 구성 가능한 한도는 config의 agents.defaults.maxToolIterations에 있습니다.

봇이 Telegram에서 아무 응답도 하지 않음

• 메시지를 보내는 동안 docker compose logs -f nanobot을 확인하세요 — 같은 순간 로그에 어떤 활동이 나타나야 합니다.

• 페어링을 완료했는지 확인하세요(섹션 6, 단계 2).

docker compose version이 "unknown flag"라고 하거나 존재하지 않음

이전 Docker Compose(v1, 하이픈 포함: docker-compose)가 있습니다. Docker Desktop을 업데이트하거나 docker-compose-plugin 플러그인을 별도로 설치하세요(Linux).

9. 프로젝트의 각 파일이 하는 일

orcamento-conversacional/
├── .env                         # SUAS credenciais (token do Telegram, chave
│                                #   do Gemini, senha do banco). Lido
│                                #   automaticamente pelo docker compose.
├── .env.example                 # Modelo de referência do .env, sem credenciais reais.
├── docker-compose.yml           # Define os containers (postgres, nanobot) e
│                                #   a ordem de inicialização.
├── Makefile                     # Atalhos opcionais (make up, make logs, etc).
├── requirements.txt             # Dependências Python do servidor MCP (mcp, psycopg2-binary).
│
├── db/
│   ├── schema.sql               # Cria as tabelas usuarios, categorias, despesas.
│   │                            #   Aplicado automaticamente na 1ª subida do Postgres.
│   └── connection.py            # Código Python que conecta no Postgres (pool de conexões)
│                                #   e resolve o usuário do Telegram para um id interno.
│
├── mcp_server/
│   ├── expense_tools.py         # As "ferramentas" que o agente de IA usa:
│   │                            #   registrar_despesa, listar_despesas, resumo_por_categoria.
│   │                            #   Roda via stdio DENTRO do container do Nanobot.
│   └── Dockerfile               # Imagem standalone opcional do MCP server (modo HTTP).
│
└── nanobot_config/
    ├── config.json              # Config do Nanobot para rodar FORA do Docker
    │                            #   (instalação local — ver seção 10). MCP via stdio
    │                            #   relativo à raiz do projeto.
    ├── config.docker.json       # Config do Nanobot para rodar DENTRO do Docker —
    │                            #   é este que está ativo quando você usa `docker compose up`.
    │                            #   MCP via stdio em /opt/mcpvenv (venv isolado).
    ├── Dockerfile               # Como construir a imagem do Nanobot. Instala o
    │                            #   nanobot + um venv isolado (/opt/mcpvenv) com as
    │                            #   dependências do servidor MCP.
    ├── SOUL.md                  # As instruções que dizem ao agente COMO se comportar:
    │                            #   como extrair valor/categoria/data de uma mensagem,
    │                            #   quando pedir confirmação, o que ele NÃO deve fazer ainda.
    ├── AGENTS.md                # Regras gerais de comportamento (idioma, uso de tools,
    │                            #   tratamento de erro). Complementa o SOUL.md.
    └── USER.md                  # Perfil do usuário — começa vazio, o Nanobot vai
                                  preenchendo automaticamente com o tempo.

현재 아키텍처 세부 사항

• 언어 모델: 공식 API를 통한 Google Gemini(providers.gemini). 모델은 .env의 GEMINI_MODEL 변수로 선택됩니다(기본값: gemini-3.6-flash). 로컬 모델은 실행되지 않습니다.

• MCP 서버: Nanobot 컨테이너 내부에서 하위 프로세스(stdio)로 실행되며, 격리된 venv /opt/mcpvenv를 사용합니다. 왜 격리인가? tools가 사용하는 Python SDK mcp 2.x가 nanobot 자체가 요구하는 버전(mcp>=1.26,<2)과 충돌하기 때문입니다.

• 루프 방지: agents.defaults.maxToolIterations: 6은 에이전트가 한 턴에 연속으로 호출할 수 있는 tool 호출 수를 제한합니다.

Nanobot 구성 파일이 두 개인 이유는?

config.json(Docker 외부에서 로컬로 실행할 때)은 프로젝트 루트를 기준으로 stdio를 통해 MCP 서버를 가리킵니다. config.docker.json(Docker 내부에서 사용)은 컨테이너의 절대 경로(/opt/mcp_server/...)와 venv /opt/mcpvenv/bin/python3를 사용합니다.

10. 대안: 로컬 설치(Docker 없이)

컨테이너 대신 Postgres/Nanobot을 컴퓨터에서 직접 실행하려는 경우(설정이 더 번거롭지만 줄 단위로 디버깅하기 쉬움):

10.1. Docker에서 Postgres만 실행

docker compose up -d postgres

(이것은 Postgres만 시작합니다. schema.sql은 자동으로 적용됩니다.)

10.2. MCP 서버의 Python 종속성 설치

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

같은 터미널에서 환경 변수를 내보냅니다:

export DATABASE_URL=postgresql://orcamento:orcamento@localhost:5432/orcamento
export TELEGRAM_TOKEN=seu_token_aqui
export GEMINI_API_KEY=sua_chave_aqui
export GEMINI_MODEL=gemini-3.6-flash

(Windows PowerShell에서는 $env:DATABASE_URL = "..." 등을 사용하세요.)

10.3. Nanobot 설치 및 실행

pip install -U nanobot-ai

nanobot_config/config.json을 ~/.nanobot/config.json으로 복사하고, nanobot_config/SOUL.md를 ~/.nanobot/workspace/SOUL.md로 복사합니다(workspace 폴더가 없으면 만드세요).

이 프로젝트의 루트에서 실행합니다(config.json의 MCP 서버 경로는 이 디렉터리를 기준으로 합니다):

nanobot gateway --config nanobot_config/config.json --verbose

Telegram 없이 테스트(추출 디버깅에 유용)

nanobot agent -c nanobot_config/config.json -m "Paguei 120 no mercado no cartão hoje"

11. 프로젝트의 다음 단계

1. 실제 메시지로 엔드투엔드 흐름을 테스트하고 관찰된 추출 오류(비공식 언어, 약어, 모호한 값)에 따라 SOUL.md를 조정합니다.

2. 전체 보고서 도구 추가(기간 비교, 지출 추이).

3. 추천 레이어 구현: resumo_por_categoria 데이터를 통합하고 API를 통해 고급 LLM으로 전송합니다.

4. 지출을 인증된 Telegram 사용자에게 자동으로 연결합니다(현재는 모델이 도구를 호출할 때 telegram_id를 전달합니다).

검증에 관한 주의사항

파이프라인은 Docker로 실제 실행하여 검증되었습니다: 컨테이너가 올라가고, MCP가 stdio를 통해 연결되어 3개의 도구가 등록되었으며, Postgres에 대한 삽입이 psql을 통해 확인되었습니다. docker-compose.yml 및 구성 JSON의 구문은 각 시작 전에 확인됩니다.

docker compose up에서 정확히 멈추는 경우 8. 일반적인 문제 섹션부터 시작하세요.