Telegram経由で自然言語による支出記録システム。Google Gemini（公式API、.envでモデル設定可能、デフォルトはgemini-3.6-flash）を言語モデルとして使用し、Nanobotがオーケストレーションし、データはPostgresに保存されます。
このドキュメントは、あなたがDockerを一度も実行したことがないことを前提としており、各ステップ、各コマンド、そしてそれぞれの結果として何が期待されるかを説明します。
Related MCP server: expense-tracker-postgres-mcp
あなたのマシンに必要なものは1つだけです。Python、Postgres、Nanobotを個別にインストールする必要はありません。これらはすべてコンテナ内で実行されます。
WindowsまたはMac: https://www.docker.com/products/docker-desktop/ からDocker Desktopをダウンロードしてインストールします。インストール後、Docker Desktopアプリを開き、「Docker is running」と表示されるのを待ちます（システムトレイのアイコンが緑色/安定します）。
Linux: お使いのディストリビューションに応じて https://docs.docker.com/engine/install/ を参照し、その後 https://docs.docker.com/engine/install/linux-postinstall/ を参照して、sudoなしでdockerを実行できるようにします。
ターミナル（WindowsではPowerShell、Mac/Linuxではターミナル）を開いて、次のコマンドを実行します:
docker --version
docker compose versionエラーなしで2つのバージョン行が表示されるはずです。
Telegram（スマホまたはデスクトップ）を開き、検索で**@BotFather**を探します。これはTelegramの公式ボットで、他のボットを作成するためのものです。認証済みバッジが付いていることを確認してください。
彼に送信: /newbot
ボットの名前を尋ねられます。任意の名前で構いません。例: 会話型予算。
次にユーザー名を尋ねられます。これはTelegram全体で一意である必要があり、「bot」で終わる必要があります。例: orcamento_seunome_bot。
成功すると、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...トークンの行全体をコピーします（形式は数字:文字と数字）。次のステップで.envファイルに貼り付けます。
このトークンを保管してください。
NanobotはGoogle Geminiの公式APIを言語モデルとして使用します。
https://aistudio.google.com/api-keys にアクセスし、Googleアカウントでログインします。
Create API keyをクリックします（Googleが自動的にプロジェクトを作成します）。
キーをコピーし、次のステップで.envに貼り付けます。
コストについて: カードは不要です。無料枠はFlash/Flash-Liteモデルをカバーし、1分あたり/1日あたりのリクエスト制限があります（モデルによって約10 req/min、約250〜1,500 req/day）— このプロジェクトには十分です。Proモデルは有料です。公式表: https://ai.google.dev/gemini-api/docs/pricing
プロジェクトには、フォルダのルート（orcamento-conversacional/.env）に**.env**というファイルがすでに含まれています。これはDocker Composeによって自動的に読み取られます。名前を変更する必要はありません。
注意: ドットで始まるファイル（.env）は、Windowsのエクスプローラー、MacのFinder、Linux/Macのls（フラグなし）ではデフォルトで「隠しファイル」です。ターミナルで表示するにはls -laを使用するか、テキストエディタでフォルダを開いてください。
.env内で、次の2行を実際の値に置き換えます:
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で実行するために変更する必要はありません。
ファイルを保存します。
orcamento-conversacionalフォルダ（docker-compose.ymlファイルがある場所）内でターミナルを開き、次のコマンドを実行します:
docker compose up -d --buildこのコマンドが行うこと（順番に）:
ステップ | 何が起こるか | おおよその時間 |
1 | ベースイメージ（Postgres）をインターネットからダウンロード | 1〜3分（初回） |
2 | Nanobotのイメージをビルド（ | 2〜4分（初回） |
3 | Postgresを起動し、 | 数秒 |
4 | Postgresが準備できるのを待ってからNanobotを起動 | 数秒 |
モデルのダウンロードや実行はあなたのマシンでは行われません。GeminiはGoogleのクラウドで実行されます。
-d（「detached」）フラグは、すべてをバックグラウンドで実行します。次回docker compose up -d（--buildなし）を実行すると、数秒で起動します。
次のコマンドを実行します:
docker compose ps2つのサービスが表示されるはずです:
NAME IMAGE STATUS
orcamento_postgres postgres:16-alpine Up (healthy)
orcamento_nanobot ...nanobot UpNanobotのログも確認してください。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 connectedorcamento_nanobotが「Restarting」と表示されたり、リストから消えたりした場合は、よくある問題のセクションを参照してください。
Telegramで、BotFatherで作成したボットのユーザー名（例: @orcamento_seunome_bot）を検索し、会話を開きます。
/startを送信します。最初の会話では、Nanobotがペアリングコードを要求する場合があります。これはログに表示されます（docker compose logs -f nanobot、行「Generated pairing code ...」）。このコードをボットに送信します。
次のようなものを送信します:
Gastei 35 no almoço hoje数秒後、ボットは登録を確認する応答を返すはずです。例:
Registrado: R$ 35,00 em alimentação (almoço).ボットが何も応答しない場合は、以下のよくある問題のセクションを参照してください。
すべてorcamento-conversacionalフォルダ内で実行します。
すべてのログをリアルタイムで表示:
docker compose logs -f（Ctrl+Cで終了します。これはログの表示を停止するだけで、コンテナは実行を続けます。）
Nanobotのみのログを表示（会話のデバッグに最も便利）:
docker compose logs -f nanobotすべてを停止（保存されたデータは保持）:
docker compose down停止後に再度起動:
docker compose up -dSOUL.md、config.docker.json、または.envを編集した後（イメージを再構築する必要はありません。設定とプロンプトはコンテナに直接マウントされます）:
docker compose up -d nanobot # recria o container aplicando o novo .envmcp_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 orcamentopsql内で、試してみてください:
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。
Error: Environment variable 'GEMINI_API_KEY' referenced in config is not set.envにGEMINI_API_KEY変数が定義されていません。.envを開き、その行が存在することを確認し（一時的な値でも）、docker compose up -d nanobotを再度実行してください。
401、unauthorized、またはinvalid api keyが表示されるGEMINI_API_KEYが間違っているか、失効しているか、余分なスペースが含まれています。https://aistudio.google.com/api-keys で新しいキーを生成し、.envを更新してください。
429またはレート制限/クォータエラーGeminiの無料枠の制限（1分あたりまたは1日あたりのリクエスト数）に達しました。オプション: 数分待つ、.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を修正してください。
docker compose logs nanobotを実行し、次のものを探してください:
MCP server 'orcamento': connected — 表示されない場合、組み込みMCPサーバーの起動に失敗しています。その行のすぐ上にあるエラーを確認してください。
Max iterations (...) reached — モデルがツール呼び出しのループに入ったことを意味します。設定可能な制限は、configのagents.defaults.maxToolIterationsにあります。
メッセージを送信しながらdocker compose logs -f nanobotを確認してください。ログに同時に何らかのアクティビティが表示されるはずです。
ペアリングを完了したかどうかを確認してください（セクション6、ステップ2）。
docker compose versionが「unknown flag」または存在しないと言う古いDocker Compose（v1、ハイフン付き: docker-compose）を使用しています。Docker Desktopを更新するか、docker-compose-pluginプラグインを個別にインストールしてください（Linux）。
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を使用します。なぜ分離するのか？ツールが使用するPython SDK mcp 2.xは、nanobot自体が要求するバージョン（mcp>=1.26,<2）と競合するためです。
ループ防止: agents.defaults.maxToolIterations: 6は、エージェントが1ターンで連続して実行できるツール呼び出しの数を制限します。
config.json（Docker外でローカルに実行するため）は、プロジェクトルートを基準にしたstdioを介してMCPサーバーを指します。config.docker.json（Docker内で使用）は、コンテナの絶対パス（/opt/mcp_server/...）とvenv /opt/mcpvenv/bin/python3を使用します。
コンテナではなく、マシン上で直接Postgres/Nanobotを実行したい場合（設定は面倒ですが、行ごとのデバッグは簡単です）:
docker compose up -d postgres（これによりPostgresのみが起動します。schema.sqlは自動的に適用されます。）
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 = "..."などを使用します。）
pip install -U nanobot-ainanobot_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 --verbosenanobot agent -c nanobot_config/config.json -m "Paguei 120 no mercado no cartão hoje"実際のメッセージでエンドツーエンドのフローをテストし、観察された抽出エラー（非公式な言語、略語、曖昧な値）に応じて SOUL.md を調整する。
完全なレポートのツールを追加する（期間比較、支出の推移）。
レコメンデーション層を実装する: resumo_por_categoria のデータを統合し、API経由で高度なLLMに送信する。
認証されたTelegramユーザーに支出を自動的にリンクする（現在は telegram_id がモデルによってツール呼び出し時に渡される）。
パイプラインはDockerでの実際の実行で検証済み: コンテナが起動し、MCPがstdio経由で3つのツールが登録された状態で接続され、Postgresへの挿入が psql で確認された。docker-compose.yml と設定JSONの構文は、各起動前に検証される。
docker compose up で正確に停止した場合は、セクション 8. 一般的な問題 から始めてください。
This server cannot be deployed
Log expenses, receipts and mileage from chat: auto-categorise, split VAT, summarise, export, rebill.
Log expenses, receipts and mileage from chat: auto-categorise, split VAT, summarise, export, rebill.
Log expenses, receipts and mileage from chat: auto-categorise, split VAT, summarise, export, rebill.
Track expenses from your AI chat: log, categorize, monthly CSV reports. All data is local.