Telegram 通知
ThreadCells は、1つの Telegram 宛先に低ノイズのライフサイクル通知を送信できます。これはインストール全体の ThreadCells 機能です。現在選択されているプロジェクトに属さず、そこから設定を読み取らず、依存もしません。
宛先を設定する
- Telegram がサポートするボット管理フローで Telegram ボットを作成または選択します。
- 宛先チャット ID を取得します。フォーラムトピックの場合は、正のメッセージスレッド ID も取得します。
- Settings → Telegram を開き、オペレーター変更をアンロックします。
- ボットトークン、チャット ID、任意のトピック/スレッド ID を入力します。
- 通知を無効にしたまま保存します。
- Check connection でボット資格情報を検証し、続けて Send test notification で宛先を検証します。
- 通知を有効にし、もう一度保存します。
テスト操作は明示的です。Settings を開いても Telegram には接続しません。通知を無効にしても、設定済みの宛先とトークンは残るため、後で再び有効にできます。Clear bot token は別の確認済みオペレーター操作です。資格情報を削除し、通知を無効にし、非シークレットの宛先フィールドは保持します。
シークレットの取り扱い
Web UI は保護された更新時にのみ新しいトークンを送信し、その後パスワードフィールドをクリアします。読み取り API は Configured、Not configured、Invalid だけを報告し、トークンを返しません。ThreadCells はトークンをブラウザーストレージ、ターミナルプロンプト、セッションまたはエージェントメタデータ、通常ログ、SQLite 設定行に置きません。
サーバーはトークンを次に保存します。
$CAO_HOME_DIR/secrets/telegram-bot-token親ディレクトリーはランタイムアカウントに制限され、トークンファイルにはモード 0600 が使われます。置き換えにはアトミックなファイルシステム rename を使います。クリアでは追跡せずに資格情報を unlink し、シークレットディレクトリーを同期します。CAO_HOME_DIR はインストールのプライベートな可変状態ルートであり、公開リポジトリーパスではありません。
このファイルは資格情報として扱ってください。ソース管理、通常のサポートバンドル、データベースエクスポート、シェル履歴、スクリーンショットにコピーしないでください。漏えいが疑われる場合は Telegram でローテーションしてください。
通知ポリシー
初回リリースのポリシーでは、永続的な各トップレベルワークフローイベントに対して最大1回の送信試行を行います。
- 成功したトップレベル完了。
- トップレベルのオーナー注意ゲート。
- ワークフローが開いている間のトップレベルターミナルの予期しない障害。
ThreadCells は、子の完了、委任、ポーリング、進捗更新、内部再試行サイクル、すべてのモデル/ツールターンには通知しません。永続的なイベントキーにより、繰り返しの観測または再起動で、すでに取得した配信が重複するのを防ぎます。
メッセージには簡潔で安全なコンテキストだけが含まれます。ThreadCells の識別情報、セッション、存在する場合はプロジェクト表示名、ライフサイクル状態、固定の要約、UTC タイムスタンプです。プロンプト、モデル出力、ファイルシステムダンプ、例外本文、オペレーターシークレット、ボットトークンは含まれません。
障害時の動作
Telegram 配信はエージェント作業に対してフェイルオープンです。タイムアウト、拒否された資格情報、利用不可の Telegram サービスは安全な結果コードを記録しますが、ワークフローを失敗させたり再開したりすることはできません。配信は上限付きの1回の試行です。通知を有効にした後、ThreadCells が無期限に再試行したり、過去のイベントを再送したりすることはありません。
Check connection は Telegram でボットトークンを検証します。Send test notification は設定済みのチャット/トピックルーティングも検証します。接続確認が成功しても、ボットが選択した宛先に書き込めることは証明されないため、新しい宛先を設定する際は両方の操作を使ってください。
バックアップと復元
非シークレットの有効/宛先状態と配信台帳は ThreadCells データベースにあります。ボットトークンは別です。災害復旧で通知を存続させる必要がある場合は、所有権とモードを保った別の暗号化済み資格情報としてトークンをバックアップしてください。通常の平文データベースアーカイブに追加しないでください。
復元後、シークレットパスと権限を確認し、通知は最初無効のままにして、両方の明示的チェックを実行してから配信を有効にします。トークンなしでデータベースを復元すると、安全に Not configured と報告されます。
トラブルシューティング
- Not configured: 有効化前に有効なボットトークンとチャット ID の両方を指定してください。
- Invalid token storage: トークンが、ランタイムアカウント所有でグループ/その他の権限がない通常の非シンボリックリンクファイルであることを確認してください。
- Connection failed: 送信 HTTPS/DNS を確認し、拒否されたボットトークンをローテーションまたは置き換えてください。安全な UI エラーは意図的に Telegram 応答詳細を省略します。
- Connection works but test fails: ボットが宛先に所属し、そこへ投稿できることを確認してください。チャット ID と任意のトピック ID を確認します。
- No lifecycle message: Enabled がオンであることを確認し、通知されるのはトップレベル完了、オーナー注意、予期しないトップレベル障害だけであることを覚えておいてください。無効時に発生したイベントは再送されません。