会話型予算 — コアパイプライン

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. インストールする必要があるもの

あなたのマシンに必要なものは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/ を参照し、その後 https://docs.docker.com/engine/install/linux-postinstall/ を参照して、sudoなしでdockerを実行できるようにします。

すべてが正しく動作しているか確認する

ターミナル（WindowsではPowerShell、Mac/Linuxではターミナル）を開いて、次のコマンドを実行します:

docker --version
docker compose version

エラーなしで2つのバージョン行が表示されるはずです。

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モデルをカバーし、1分あたり/1日あたりのリクエスト制限があります（モデルによって約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内で、次の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で実行するために変更する必要はありません。

ファイルを保存します。

5. Dockerですべてを起動する

orcamento-conversacionalフォルダ（docker-compose.ymlファイルがある場所）内でターミナルを開き、次のコマンドを実行します:

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またはレート制限/クォータエラー

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にあります。

ボットが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を使用します。なぜ分離するのか？ツールが使用するPython SDK mcp 2.xは、nanobot自体が要求するバージョン（mcp>=1.26,<2）と競合するためです。

• ループ防止: agents.defaults.maxToolIterations: 6は、エージェントが1ターンで連続して実行できるツール呼び出しの数を制限します。

なぜNanobotの設定ファイルが2つあるのか？

config.json（Docker外でローカルに実行するため）は、プロジェクトルートを基準にしたstdioを介してMCPサーバーを指します。config.docker.json（Docker内で使用）は、コンテナの絶対パス（/opt/mcp_server/...）とvenv /opt/mcpvenv/bin/python3を使用します。

10. 代替案: ローカルインストール（Dockerなし）

コンテナではなく、マシン上で直接Postgres/Nanobotを実行したい場合（設定は面倒ですが、行ごとのデバッグは簡単です）:

10.1. PostgresのみをDockerで起動

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. 一般的な問題 から始めてください。