Telegram

ZeroClaw エージェントを Telegram ボットとしてロングポーリングで実行します。公開 URL や Webhook は必要ありません。このガイドでは、まずランタイムの接続設定を行い、次にボットの作成から最初の認証済み会話までを順に説明します。

現在の実装がどのように連携しているか

Telegram のセットアップには、3 つの独立した信頼できる情報源があります。channel ブロックが Telegram 接続を管理し、agent ブロックがルーティングを管理し、peer グループが受信認可を管理します:

flowchart LR
    T["channels.telegram.home<br/>token and channel behavior"] --> C["TelegramChannel<br/>alias = home"]
    P["matching peer groups<br/>authorized Telegram identities"] --> C
    G["Telegram Bot API<br/>getUpdates long poll"] --> C
    C -->|"authorized ChannelMessage"| R["AgentRouter"]
    A["agents.primary<br/>channels includes telegram.home"] --> R
    R --> L["agent turn and Telegram reply"]

collect_configured_channels は、有効化されたエージェント所有のエイリアスごとに TelegramChannel を1つ構築します。このチャンネルは、メッセージが届くたびに共有 Config から一致するピアグループメンバーを解決します。送信者の数値 Telegram ユーザーIDまたはユーザー名のいずれかを受け付け、認可済みの ChannelMessage を共有チャンネルディスパッチおよびエージェントターンライフサイクルに渡します。

[channels.telegram.<alias>] の下に allowed_users フィールドはありません。認可は Peer Groups にあり、そのページがピアグループのフィールド、マッチング、マルチエージェントの動作に関する正式なリファレンスです。

1. Telegram ボットを作成する

1. Telegram で @BotFather を開きます。
2. 表示名とユーザー名の入力を求められるので、/newbot を送信してその指示に従ってください。
3. ボットトークンをコピーします。Telegram の公式チュートリアルでも同じ手順が説明されています。

トークンはパスワードと同じように扱ってください。これを持っている人は誰でもボットを制御できます。config.toml、ログ、スクリーンショット、またはソース管理に貼り付けないでください。

2. エイリアスを設定してエージェントにアタッチする

このガイドでは、チャンネルエイリアスとして home、エージェントエイリアスとして primary を使用します。エイリアスはこのボットインスタンスに対する ZeroClaw のローカル名であり、Telegram のボットユーザー名と一致させる必要はありません。

マスクされたシークレットプロンプトを使ってトークンを設定し、チャンネルを有効にします:

zeroclaw config set channels.telegram.home.bot_token
zeroclaw config set channels.telegram.home.enabled true

エージェントのエイリアスを一覧表示し、次に対象エージェントの既存のチャンネルリストに telegram.home を追加します。値を省略するとリストエディタが開くため、他のチャンネルバインディングを破棄せずに新しいエントリを追加できます。

zeroclaw agents list
zeroclaw config set agents.primary.channels

その後、関連する非機密構造は次と同等です:

[channels.telegram.home]
enabled = true
# bot_token は、マスクされた `config set` プロンプトの後に暗号化されて保存されます

[agents.primary]
channels = ["telegram.home"]

primary を、すでに動作するモデルプロバイダーとリスクプロファイルを持つ既存のエージェントに置き換えます。構成内のいずれかのエージェントが channels リストを宣言すると、有効化されていても、有効なエージェントの channels リストに含まれていないチャネルは起動されません。エージェントがチャネルバインディングを1つも宣言していない場合、ZeroClaw は代わりに従来のルーティングにフォールバックします。つまり、有効化されているすべてのチャネルが起動され、解決されたデフォルトの有効なエージェントによって処理されます。上記のように明示的なバインディングを宣言して、リストにないボットがデフォルトエージェントの下でひそかに実行されるのではなく、確実に非アクティブになるようにしてください。

3. 最初のユーザーの認可方法を選択する

ボットを起動する前に、次のいずれかのパスを選択してください。

最初のユーザーをワンタイムコードとペアリングする

プライベートな初回実行では、解決される外部ピアのセットを空のままにします。特に、channel が telegram または telegram.home のいずれかであるピアグループは、external_peers エントリを一切提供してはなりません。外部ピアを提供せず、他の設定のみを持つ一致グループは、ペアリングに影響しません。

TelegramChannel が解決済みピアなしで構築されると、1 回限りのペアリングコードを作成し、それをフォアグラウンド出力と構造化ログに書き込みます。最初の承認済みユーザーが Telegram で /bind を使ってそれを使用します。

既知のユーザーを事前承認する

数値の Telegram ユーザー ID がすでにわかっている場合は、起動前にそれらを認可してください。ユーザーがアカウント名を変更しても安定しているため、ユーザー名よりも数値 ID の方が望ましいです。これは最小限のエイリアススコープの例です:

[peer_groups.telegram_home]
channel = "telegram.home"
external_peers = ["111111111", "222222222"]

タイプ全体に channel = "telegram" を使用するのは、設定されたすべての Telegram エイリアスで同じアイデンティティを受け入れる場合のみにしてください。完全なスキーマと解決ルールについては、Peer Groups を参照してください。

解決済みの外部ピアセットが空でない場合、そのチャネルインスタンスでは最初のユーザーによるペアリングが無効になります。これにはワイルドカードのピアグループも含まれます。

[!CAUTION] external_peers = ["*"] は、ボットに到達できるすべての Telegram 送信者を受け入れ、ワンタイムペアリングフローを無効にします。これらの送信者はエージェントと、そのリスクプロファイルが許可するすべてのツールを操作できます。ワイルドカードは、適切に制限されたエージェントを持つ意図的に公開されたボットにのみ使用してください。プライベートセットアップの近道ではありません。

4. チャンネルを開始して検査する

通常の操作にはフルデーモン、フォアグラウンドの診断実行にはチャンネル専用プロセス、長期稼働にはインストール済みサービスを使用します：

zeroclaw daemon

# 代替フォアグラウンド診断: 構成済みのすべてのチャネルを開始します。
zeroclaw channel start

# ZeroClaw が管理対象サービスとしてインストールされている場合。
zeroclaw service restart

TelegramはgetUpdatesロングポーリングを使用するため、インバウンドポートやパブリックコールバックURLは必要ありません。別のターミナルで、接続を確認してログを追跡します：

zeroclaw channel doctor
zeroclaw service logs --follow

ピアセットが空の場合は、Telegram pairing required; one-time bind code issued を探します。構造化イベントにはチャネルエイリアスと pairing_code が含まれます。フォアグラウンドでの zeroclaw daemon と zeroclaw channel start の実行でも、コードが直接出力されます。コードが使用されるまで、コードとログ出力を機密情報として扱ってください。

5. 最初のユーザーを/bindとペアリングする

承認したいTelegramアカウントから、印刷されたコードをボットに送信してください：

/bind 123456

認証パスは以下のとおりです：

flowchart TD
    S["Telegram update arrives"] --> I["Read username and numeric user ID"]
    I --> M{"Either identity matches<br/>the resolved peer set?"}
    M -->|"yes"| D["Dispatch ChannelMessage to the owning agent"]
    M -->|"no"| B{"Message is /bind code?"}
    B -->|"no"| H["Reply with the alias-aware operator bind command"]
    B -->|"yes, pairing active"| V{"One-time code is valid?"}
    V -->|"no"| X["Reject; repeated failures can lock out retries"]
    V -->|"yes"| P["Add numeric user ID to peer_groups.telegram_home"]
    P --> W["Save config.toml and accept subsequent messages"]

成功すると、ZeroClaw は安定した数値の送信者 ID を優先し、telegram.home 用に [peer_groups.telegram_home] に追加して、config.toml を保存します。実行中のチャネルのピアリゾルバーはその共有設定を読み取るため、ユーザーは再起動なしですぐに次のメッセージを送信できます。

コードは一度しか使えません。以降の再起動では、保存済みのピアによって解決済みセットが空でなくなるため、ペアリングは無効のままとなり、代替コードは発行されません。永続化に失敗したため、ボットが現在の実行時に限ってペアリングされたと通知した場合は、再起動する前に、報告された設定の権限エラーまたは書き込みエラーを修正してください。

6. operator CLI から別のユーザーをバインドする

権限のないユーザーは、ボットにメッセージを送信して、そのユーザーの数値 ID を含む推奨オペレーターコマンドを受け取ることができます。そのコマンドを ZeroClaw ホスト上で実行します。home エイリアスの場合、その形式は次のとおりです:

zeroclaw channel bind-telegram 111111111 --alias home

先頭の @ を付けずに Telegram のユーザー名をバインドすることもできます:

zeroclaw channel bind-telegram example_user --alias home

--alias は [channels.telegram.<alias>] のキーと一致する必要があります。CLI はデフォルトで default を使用するため、設定済みのチャンネルが実際に [channels.telegram.default] である場合にのみフラグを省略してください:

zeroclaw channel bind-telegram 111111111

このコマンドは、実行中のチャネルが読み取ることのないピアグループを作成する代わりに、不明なエイリアスを拒否します。有効なエイリアスの場合は [peer_groups.telegram_<alias>] を作成または更新し、グループのスコープを telegram.<alias> に限定して、アイデンティティを冪等に保存します。

再起動と永続化の動作

自動リロードが失敗した場合、bindコマンドは保存した変更を保持し、手動での再起動を促します：

zeroclaw service stop
zeroclaw service start

ログとトラブルシューティング

インストール済みサービスの場合:

zeroclaw service logs --lines 200
zeroclaw service logs --follow

フォアグラウンド実行では、プロセスの出力を読み取ります。永続的な構造化ログが有効になっている場合、イベントはインストールディレクトリ配下の data/state/runtime-trace.jsonl にも書き込まれます。オブザーバビリティを参照してください。

Telegram の全フィールド一覧は、実行中の設定スキーマから生成されます：

zeroclaw config set channels.telegram.<alias>.ack_reactions <value>

export ZEROCLAW_channels__telegram__<alias>__ack_reactions=

zeroclaw config set channels.telegram.<alias>.api_base_url <value>

export ZEROCLAW_channels__telegram__<alias>__api_base_url=

zeroclaw config set channels.telegram.<alias>.approval_timeout_secs <value>

export ZEROCLAW_channels__telegram__<alias>__approval_timeout_secs=

zeroclaw config set channels.telegram.<alias>.bot_token    # マスクされた入力、暗号化して保存

export ZEROCLAW_channels__telegram__<alias>__bot_token=

zeroclaw config set channels.telegram.<alias>.debounce_ms <value>

export ZEROCLAW_channels__telegram__<alias>__debounce_ms=

zeroclaw config set channels.telegram.<alias>.draft_update_interval_ms <value>

export ZEROCLAW_channels__telegram__<alias>__draft_update_interval_ms=

zeroclaw config set channels.telegram.<alias>.excluded_tools <value>

export ZEROCLAW_channels__telegram__<alias>__excluded_tools=

zeroclaw config set channels.telegram.<alias>.interrupt_on_new_message <value>

export ZEROCLAW_channels__telegram__<alias>__interrupt_on_new_message=

zeroclaw config set channels.telegram.<alias>.mention_only <value>

export ZEROCLAW_channels__telegram__<alias>__mention_only=

zeroclaw config set channels.telegram.<alias>.proxy_url <value>

export ZEROCLAW_channels__telegram__<alias>__proxy_url=

zeroclaw config set channels.telegram.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__telegram__<alias>__reply_min_interval_secs=

zeroclaw config set channels.telegram.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__telegram__<alias>__reply_queue_depth_max=

zeroclaw config set channels.telegram.<alias>.stream_mode <value>

export ZEROCLAW_channels__telegram__<alias>__stream_mode=

関連項目も参照してください

• ピアグループ: 正規の受信認可スキーマ
• チャネルランタイムのライフサイクル
• サービス管理
• オブザーバビリティ