工房からのノート
メッセージアプリの中に住むエージェントについての私たちの考え方、構築を通じて学んだこと、そして今日から使える実践的なヒントをお届けします。
329件の記事
すべての記事
OpenClawが外部に送信するもの
OpenClawはデフォルトで1日1回外部へリクエストを送信し、その内容はドキュメントに正確に書かれています。バージョン、オペレーティングシステム、Node.jsのバージョン、アーキテクチャ、サーフェスで、インストール識別子は含まれません。Cloudflareから導出されて3か月間保持される位置情報も含めた全体像と、リクエストを止めるすべてのスイッチを紹介します。
OpenClawのコントロールUI
Gatewayはポート18789でブラウザ用のダッシュボードを提供し、最初に表示されるのは「Gateway secret」という1つの入力欄です。この欄が受け付ける値、同じマシン上のブラウザでも入力が必要な理由、エージェント一覧とチームモードの働き、そしてLAN URLがブロックされたときに実行すべきコマンドを解説します。
Failed to start Chrome CDP on port 18800
エラーは1行だけで、手がかりはありません。Linuxサーバーでは、原因はほぼ必ずブラウザです。apt install chromiumで入るのはsnapのラッパーで、その閉じ込め（confinement）が、OpenClawがChromeを起動して監視する仕組みを壊します。ここでは修正方法、重要な6つの設定、そしてCDPの起動失敗とナビゲーションのブロックを見分けるチェックを紹介します。
OpenClawのブラウザリレー
OpenClawは、Gatewayのマシン上にないブラウザも操作できます。ノードホストが操作を中継するか、cdpUrlでホスト型のChromiumに接続します。以下では、ルーティング、プロファイル、認証情報の挙動を説明します。
OpenClawのACPエージェント
OpenClawは、Agent Client Protocolを介して外部のコーディングハーネスを実行します。Claude Code、Gemini CLI、Cursor、Copilot、Droid、OpenCode、ほか11種類を、チャットメッセージから起動し、バックグラウンドタスクとして追跡します。2つのコマンドで済むacpxのインストール、plugins.allowの罠を含む初回実行の落とし穴、そもそもこの経路が提示されるかどうかを決める前提条件のチェックリスト、そして17個のハーネスのターゲットIDについて説明します。
GmailからOpenClawを起動する
Gmailの受信トレイのイベントは、Google Pub/Subのトピック、ウォッチャープロセス、GatewayのHTTPフックを経由してOpenClawに届きます。組み込みのプリセットはメールごとに専用のセッションを与えますが、それ以外は何も制限しません。以下では、gcloudでのトピックとwatchの設定、2つのトークンのモデル、ドキュメントが推奨する制限付きでサンドボックス化されたmail_readerエージェント、そしてリーダーが本当に封じ込められているかを確かめる境界テストを説明します。
意図してサンドボックスを抜け出す
elevatedモードを使うと、サンドボックス化されたOpenClawエージェントが、設定可能な承認ゲートのもとで、サンドボックスの外でコマンドを実行できます。もともとサンドボックス化されていないエージェントには何の効果もなく、ツールポリシーや、そもそもサンドボックス化を必須とするロールを上書きすることもできません。この記事では、4つのディレクティブ、解決の順序、すべて通過しなければならないゲートと許可リスト、そして昇格が意図的に手を触れないものを取り上げます。
OpenClawのコンテキストエンジン
コンテキストエンジンは、どのメッセージをモデルに渡すか、古い履歴をどう要約するか、コンテキストがサブエージェントの境界をどう越えるかを決めます。OpenClawにはlegacyエンジンが同梱されていてデフォルトで使われ、プラグインエンジンは設定のスロットで選択します。インターフェースはingest、assemble、compactを必須とし、bootstrap、maintain、バッチでのingest、サブエージェント用フックは任意です。失敗したプラグインエンジンはそのプロセスの間隔離され、処理はlegacyにフォールバックします。また、ownsCompactionをfalseにしても、legacyのコンパクション経路は復活しません。
OpenClawのバックグラウンドexecとprocessツール
yield遅延を超えて実行されるコマンドは、ブロックする代わりにセッションIDと出力末尾の短い抜粋を返します。出力は合計上限までメモリに保持され、終了したセッションは完了時点から測る保持期間で期限切れになり、保持されるのは最大50件の終了済みセッションと200万文字までです。ノードを基盤とするワーカー環境はターンをまたいでバックグラウンドコマンドを生かし続け、processツールはポーリング、ページ単位のログの読み取り、stdinへの書き込み、キー送信、送信確定、貼り付け、終了、消去を行います。
OpenClawのexecツール
execはワークスペースでシェルコマンドを実行し、選択したホストが許す場所ならどこでもファイルを作成、編集、削除できます。そのため、ファイルツールを無効にしてもexecは読み取り専用になりません。hostパラメーターは、サンドボックスのランタイムが有効ならサンドボックスに、そうでなければgatewayに解決されます。modeキーでdeny、allowlist、ask、auto、fullを設定し、自動レビュアーは対象となる不一致に対してallow、deny、askを返します。その際、ディスパッチチェーン全体がバインドされ、起動前に再チェックされます。セッションコマンドはポリシーを厳しくすることしかできません。
OpenClawのOpenResponses API
gatewayは、gateway.http.endpoints.responsesを有効にするとOpenResponses互換のresponsesエンドポイントを提供し、認証、スコープ、エージェントの指定のルールはchat completionsと同じです。入力は文字列またはアイテムのリストで、ツールの結果はfunction_call_outputとして返され、previous_response_idは同じエージェント、ユーザー、セッションのスコープ内でセッションを再利用します。ファイルは信頼できないコンテンツとしてデコードされてシステムプロンプトに入り、テキストが少ないPDFはラスタライズされます。ストリーミングでは型付きのresponseイベントが送出され、DONEで終わります。
OpenClawの信頼済みプロキシ認証
trusted-proxyモードのgatewayは、信頼済みプロキシとして登録された送信元アドレスから届いたユーザーアイデンティティのヘッダーだけを信頼し、オプトインが意図的に有効にされていない限りループバックの送信元を拒否し、自身のインターフェースに一致する送信元を拒否し、設定されたヘッダーと許可リストへの一致を必須とし、共有トークンも設定されている場合は起動を拒否します。セキュリティ監査はこのモードを意図的にcriticalとして報告します。アイデンティティスコープは検証済みユーザーにセッション限定のスコープを付与し、デバイスの自動承認はプロキシのアイデンティティを登録の境界にでき、スコープヘッダーは絞り込むことしかしません。
OpenClawのexec承認・上級編
cut、head、tail、tr、uniq、wcといったsafe binsは、ファイル引数やパスのようなトークンを拒否するため、allowlistモードでもエントリーなしで実行されます。grepとsortはオプトインで、awk、sed、jqは決してsafe binsにならず、インタープリターもそこに含めるべきではありません。safe binsは、ほかのディレクトリを信頼済みにしない限り、デフォルトのシステムディレクトリから解決される必要があります。連結はすべてのセグメントが通過すれば許可され、インタープリターの実行はレビューの前にディスパッチチェーン全体をバインドし、承認の解決にはwriteではなく専用のapprovalsスコープが必要で、プロンプトはSlack、Telegram、Discordなどに転送できます。
OpenClaw gatewayのトラブルシューティング
詳細なgatewayランブックは、同じ5つのコマンドを順に実行することから始まり、実行中のランタイム、okの接続プローブ、capability行が表示されることを確認したうえで、症状に応じて6つのページに振り分けます。アップデートとロールバック、スキルとモデルプロバイダー、エージェントの応答とコントロールインターフェース、gatewayのサービスとプロセス、設定の検証とプローブ、チャネル配信とツールです。アップグレード後の不具合のほとんどは設定のずれか、より厳格になったデフォルトによるもので、gatewayのモードとリモートURL、本物の認証経路が必要になった非ループバックのbind、保留中のデバイスまたはダイレクトメッセージのペアリング承認を確認することで切り分けます。
OpenClawのOpenAI互換HTTP API
gateway.http.endpoints.chatCompletionsを有効にすると、gatewayは自身のポートでchat completions、models、embeddingsを提供できます。有効なトークンはオーナーレベルのアクセス権になるため、ドキュメントはループバック、tailnet、プライベートなイングレスに限定するよう求めています。modelフィールドはプロバイダーのモデルではなくopenclaw/defaultのようなエージェントを指し、user文字列からは安定したセッションキーが導出され、x-openclaw-modelはバックエンドのモデルを上書きします。関数ツール、tool_choice、SSEストリーミングはOpenAIの形式に従い、制限事項も文書化されています。
OpenClawのオペレータースコープ
スコープは、gatewayクライアントが認証後に何をできるかを制限するもので、敵対的なマルチテナント分離ではなく、信頼された1つのオペレータードメイン内のガードレールとして機能します。operator.writeはreadとtalkを含み、operator.adminはすべてを含みます。名前付きロールはスコープに上限を設け、作成者ごとのサンドボックス化を必須にできます。アイデンティティへの付与は、検証済みのプロキシまたはTailscaleのアイデンティティにスコープを結び付けます。各RPCには最小権限のメソッドスコープがあり、デバイスのリクエストを承認しても、承認者がすでに持つスコープしか発行できません。
OpenClawのMatrixアクセス制御
Matrix経由で誰がOpenClawにメッセージを届けられるのか、そしてメッセージの周囲に何を保持するのかを解説します。他の設定済みOpenClaw Matrixアカウントからのメッセージはデフォルトで無視されること、trueまたはmentionsを取りルームごとに上書きできるallow-bots設定、共有のループ保護とその優先順位、自身のIDに関するルール、ボットのフラグがないプラットフォームでの「ボットによる送信」の定義、トリガーは決めずに取得した返信、スレッドのルート、保留中の履歴を絞り込む3つのコンテキスト可視性モード、許可リストとメンション必須のルームを使ったDMとルームのポリシーの例、DMの完全な無効化、ペアリングのコマンドと、クールダウン後のリマインダーを伴う保留中コードの再利用、そしてボット自身のメンションを前置すればルームでも認識され、同じ認可が引き続き適用されるスラッシュコマンドです。
静かなプレビューのためのOpenClaw Matrixプッシュルール
Matrixのquietストリーミングを適切なタイミングで鳴らすための、ホームサーバー側の設定です。プレビューは通知しないnoticeとして送信され、確定した編集にはマーカーが付き、クライアントはユーザーごとのプッシュルールがそのマーカーに一致したときだけ通知します。progressモードも同じ経路で確定します。前提条件は、受信者ユーザー、ボットユーザー、受信者のトークン、送信者としてのボットの完全なID、正常なpusherです。quietモードの有効化からトークンの発行または再利用、pusherの一覧表示、4つの条件と通知アクションを持つoverrideルールのインストール、その確認とストリーミング返信のテストまでの6つのステップ、削除方法、ボットごと・受信者ごとに一意で再実行するとその場で更新されるルールID、サーバーのsuppressルールより前に挿入されるユーザーのoverrideルール、ルールが影響するテキストのみの編集（メディア、古いプレビューのフォールバック、メンションを発動する最終メッセージは通常どおり通知）、2023年に追加されたevent-property-is条件を必要とし、古いリリースでは何も言わずに一致しないSynapse、そしてTuwunelのアクティブデバイス抑制オプションについて解説します。
OpenClawのMicrosoft Teams設定
チャネルブロック配下のTeams設定を解説します。環境変数で代替できる8つの認証キー（それ以外はすべて設定でのみ指定）、フォールバックを伴う履歴の上限と、親メッセージと最大50件の返信を加えつつ引用されたコマンドを実行させないGraphのスレッドコンテキスト、all、allowlist、allowlist-quoteの可視性モード、ユーザーごとのDM履歴の上限、パブリック、米国政府、DoD、中国の各クラウド向けのクラウドキーとサービスURLキー、webhookのポートとパス、AADオブジェクトIDが推奨される4つのDMポリシー、デフォルトの送信先、非常用の名前照合スイッチ、4000文字のチャンク上限、改行によるチャンク分割、メディアホストの許可リストとGraphメディアのフォールバック、ツールポリシーを含むチームごと・チャネルごとの上書きに対応したメンション要件と返信スタイル、グループでのアップロードに使うSharePointサイト、プロンプトスターター付きのウェルカムカードとグループウェルカムカード、応答プレフィックス、振り返り付きのサムズフィードバック、委任されたGraphスコープを使うSSOです。
OpenClawのTelegramセットアップ
ゼロからTelegramボットをOpenClawに接続する方法です。どちらもトークンの取得で終わるBotFatherのチャットとウェブの2つの手順、それを設定に書き込むchannels addコマンド、pairingのDMポリシーとワイルドカードのグループエントリーを使った手書きの代替手段、デフォルトアカウントにしか使えない環境変数のフォールバック、Telegramにloginコマンドがない理由、ホットリロード下でのステータスプローブ、1時間で期限切れになるコードを扱うpairingのlistコマンドとapproveコマンド、グループに必要な2つのIDとそれぞれの置き場所、アカウントを考慮したトークンの優先順位と24時間のアイデンティティキャッシュ、Telegram側のプライバシーモードと管理者ステータス、そして削除して再追加するルール、便利なBotFatherの切り替え設定、さらにトランスポートの選択として、永続的な再開位置を持つロングポーリングと、シークレット、リスナーのデフォルト値、予約済みのヘルスパス、永続的な受け入れを示すヘッダーを持つwebhookモードを解説します。
OpenClawのSlackグラフ、テーブル、承認
OpenClawがSlackでネイティブに描画するBlock Kitのサーフェスを解説します。追加のスコープなしでSlackのデータ可視化ブロックにマッピングされるポータブルなグラフブロック、タイトル、セグメント、系列、カテゴリに課される制限、すべてのグラフが持つテキスト表現、Slackがブロックを拒否したときの復旧、ドキュメントに記載のない1メッセージ2グラフの上限と超過分のグラフが後続メッセージに回る仕組み、生のテキストセル、生の数値セル、行ヘッダーを備えた現行のデータテーブルにマッピングされるポータブルなテーブルブロック、20列・100行・10,000文字という上限、完全なテキストへのフォールバックと編集時の明示的なサイズエラー、Markdownのパイプテーブルがテキストのままで生のブロックは引き続き通過する理由、受信した貼り付けテーブルのTSV化、プラグインが所有するモーダル送信の2つのルーティングパターンとエージェントに届くコンパクトで秘匿化されたイベント、そして承認者、ターゲット、フィルター、Enterprise Gridのワークスペース保持を備えた、execとプラグインのリクエスト向けネイティブ承認クライアントとしてのSlackです。
OpenClawのSlackスレッドとセッション
SlackのメッセージがOpenClawのどこに届き、返信がどこへ行くのかを解説します。DMはdirect、チャンネルはchannel、グループDMはgroupとしてルーティングされること、Slackのターゲット形式を受け付けるルートバインディング、通常のDMを1つにまとめるmainのDMスコープ、チャンネルごとのセッションと親のタイムスタンプから取られるスレッドのサフィックス、メンションとそのスレッドを1つのセッションに保つシードされたルート、履歴のスコープ、親の継承と最初の履歴取得、2つの暗黙のメンションのフラグと移行された明示的メンションのキー、チャンネルごと・チャットタイプごとの返信モードとレガシーのDMフォールバック、手動の返信タグ、テキストとBlock Kitでの返信のブロードキャスト、トップレベルのオプトアウト、Telegramと違ってSlackではoffが明示的なタグも無効にする理由、そして入力欄から始まるルートがそれぞれ独立した会話となり、マーカーが3つのシグナルから学習されてアカウント、ワークスペース、アプリごとに保持されるAgent ViewのDMです。
OpenClawのTelegramリッチメッセージと承認
OpenClawのTelegramボットが使えるリッチなサーフェスを解説します。太字、斜体、リンク、コード、スポイラー、引用に対応したデフォルトの標準Telegram HTML、Markdownを見出し、テーブル、details、チェックリスト、数式などの型付きBot API 10.3ブロックとして描画し、キャプションは引き続きHTML、20列を超えるテーブルはコードにフォールバックするrich-messagesフラグ、クライアントの互換性のためにこのフラグがオフのままである理由、リンクプレビュー、allowlistをデフォルトとする5つのインラインボタンスコープ、callbackとweb-appのアクションを持つbuttonsブロックとMini Appのプライベートチャット限定という制約、どのハンドラーにも処理されなかったコールバックがテキストとしてエージェントに届く仕組み、永続的な受信処理での応答確認、エイリアスとデフォルトでオフのゲートを持つ6つのメッセージアクション、emoji-listによる確認、そして承認者、ターゲット、有効期限、インラインボタンの要件を備えたexec承認です。
OpenClawのMatrix暗号化と検証
OpenClawのMatrixアカウントがエンドツーエンド暗号化を得て、信頼された状態を保つ仕組みを解説します。シークレットストレージ、クロス署名、ルームキーのバックアップをブートストラップするセットアップコマンド、リカバリーキーをstdin経由で渡す理由、3つの独立した信頼シグナルと、クロス署名による検証だけがverified by ownerとみなされるというルール、デバイスの検証と自己検証、ブートストラップ兼修復コマンドとそのUIAフォールバック、バックアップの状態、復元とリセット、SAS検証のコマンド、マルチアカウントに関する注意点、クールダウン付きの起動時自己検証、検証の通知、そしてデバイスが削除された場合の対処です。
50件中24件の記事を表示中
ブログのその他の記事は英語で公開しています。 英語で読む
読むだけでなく、作ってみましょう
エージェントを設定してチャネルを選べば、いつも開いているアプリの中でエージェントが働き始めます。