Call Grok Bot

call-grokbot

Codex と Claude Code から、既存の Grok Bots に質問できます。ローカルの stdio MCP サーバーが、1 つの完結したタスクを送信し、応答を逐次読み取り、接続中の ボットに割り込みます。ボットは既存の会話、メモリ、接続済みツールをそのまま使います。

非公式です。Cursor / Anysphere、xAI / Grok、OpenAI、Anthropic とは提携関係になく、承認やサポートも受けていません。 Grok Bot RPC は文書化されておらず、変更される可能性があります。公開されているモデル推論エンドポイントは提供されていません。

English · 日本語 · Español · Português (Brasil) · 简体中文 · 繁體中文

認証の詳細

デモを見る

カバーをクリックすると、YouTube で 50 秒のデモを視聴できます（英語のナレーション）。

仕組み

始める前に

• Node.js 22.13+、npm、Git をインストールします。
• 使用するクライアント（Codex または Claude Code）をインストールして、サインインします。 コーディングクライアントのアカウントは、以下で使用する Cursor のログインアカウントとは別です。
• 公式 Cursor CLI をインストールします。
• Grok Bot アカウントと、既存のボットを 1 つ以上用意します。アプリに表示される正確なボット名を使ってください。このパッケージではボットを作成できません。

Codex または Claude Code のプラグインガイドを選んでください。どちらのプラグインにも consult スキルが含まれ、バージョンを固定した npx パッケージで MCP サーバーを起動します。 call-grokbot のグローバルインストール、ソースのチェックアウト、npm アカウント、 個人用 API キーは必要ありません。

macOS のブラウザー認証では、公式 CLI のログイン用 Keychain エントリーを使用します。 Linux と Windows では、公式 CLI の認証ファイルを使用します。MCP 設定にトークンをコピーしないでください。実アカウントを使ったプラグインテストは macOS で合格しています。Linux と Windows は CI でカバーされていますが、実アカウントのログインフローは検証されていません。

プラグインのリリース 0.1.2 では、npm ランタイム 0.1.1 を使用します。その npx コマンドは 公式 npm tarball の URL を固定するため、npm が同じ名前の現在のソースチェックアウトに置き換えることはありません。これにより、このリポジトリ内での command not found と MCP の CONNECTION_CLOSED が解消され、キャッシュが空の場合でも動作します。グローバルなパッケージのインストールは不要です。

Codex プラグインのクイックスタート

1. ターミナルでプラグインをインストールする

codex plugin marketplace add ZensHQ/call-grokbot --ref plugin-v0.1.2
codex plugin add call-grokbot@call-grokbot
codex plugin list

call-grokbot@call-grokbot がインストールされ、有効になっていることを確認します。これらは ターミナルコマンドです。Codex のインストール環境で plugin が認識されない場合は、プラグインコマンドに対応したバージョンに更新してください。公式 Codex プラグインのドキュメントを参照してください。

2. ターミナルでボットのアカウントにサインインする

npx --yes https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz login
npx --yes https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz doctor

login は公式 Cursor CLI の agent login を実行します。ブラウザーで、ボットを所有するアカウントを選択し、セキュリティチェックがあれば完了してください。doctor は認証情報を表示せずに、"authenticated": true、"authMode": "browser"、"cursorCliFound": true を報告する必要があります。

3. 新しい Codex セッションを開いて、スキルを呼び出す

作業したいプロジェクトから Codex を起動します。

codex

これをターミナルではなく、Codex の会話内で入力します。

$call-grokbot:consult List my existing bots. Do not send any message.

結果から正確な名前を選びます。以下の例では、 Research Bot を実際のボット名に置き換えてください。

$call-grokbot:consult Ask my existing bot "Research Bot" to reply exactly PONG.
Send the task once. If it is running, use check until it finishes; do not resend.

これにより、そのボットの既存の会話に実際のメッセージが送信されます。確認が成功したとみなされるのは、PONG を受信し、かつタスクが finished に到達した場合です。最初の応答だけでは不十分です。実際のタスクでは、PONG のリクエストを、関連する事実、制約、許可されたアクション、希望する出力を含む、単独で完結したブリーフに置き換えてください。

Claude Code プラグインのクイックスタート

1. ターミナルでプラグインをインストールする

claude plugin marketplace add ZensHQ/call-grokbot
claude plugin install call-grokbot@call-grokbot --scope user
claude plugin list

call-grokbot@call-grokbot が有効になっていることを確認します。ユーザースコープにすると、このマシン上の Claude Code プロジェクトで利用できるようになります。すでに Claude Code を起動している場合は、対話型の方法でも実行できます。

/plugin marketplace add ZensHQ/call-grokbot
/plugin install call-grokbot@call-grokbot

対話型のインストールパネルで、Install for you（ユーザースコープ）を選択します。他のインストールスコープについては、Claude Code の公式プラグインドキュメントをご覧ください。

2. ターミナルでボットのアカウントにサインインする

npx --yes https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz login
npx --yes https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz doctor

ボットを所有するアカウントで、公式 Cursor CLI のブラウザーサインインを完了します。doctor の結果で "authenticated": true、"authMode": "browser"、"cursorCliFound": true と表示されることを確認します。このマシンで Codex プラグインのためにすでにサインインしている場合は、両方のプラグインで公式 CLI のセッションが共有されます。再度サインインする代わりに、npx --yes https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz doctor を実行して確認してください。

3. 接続を確認してから、新しい Claude Code セッションを開く

ターミナルで実行します。

claude mcp list
claude

ヘルスチェックで plugin:call-grokbot:call-grokbot が接続済みと表示されるはずです。最初のリクエストを送る前に、サーバーの接続が完了するまで待ちます。インストール前からセッションを開いていた場合は、新しいセッションを開始し、プラグインとスキルが読み込まれるようにします。

これを Claude Code の会話内で入力します。

/call-grokbot:consult List my existing bots. Do not send any message.

以下の Research Bot を、結果に表示された既存の正確な名前に置き換えます。

/call-grokbot:consult Ask my existing bot "Research Bot" to reply exactly PONG.
Send the task once. If it is running, use check until it finishes; do not resend.

これはボットの会話に送信される実際のメッセージです。PONG と finished の両方を確認してください。通常の作業では、ブリーフに関連する内容を記載してください。ボットは Claude Code のセッションやプロジェクトファイルを自動的に参照できません。

セットアップのトラブルシューティング

症状	対処方法
call-grokbot: command not found	プラグインをインストールしても、グローバル実行ファイルは追加されません。ターミナルで npx --yes https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz login または npx --yes https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz doctor を使用してください。
call-grokbot のソースチェックアウト内で command not found または CONNECTION_CLOSED が発生する	プラグイン 0.1.2 と、そこで指定されている npm tarball URL を使用してください。ターミナルコマンドだけに修正を加えても、インストール済みのプラグインは更新されません。以前の --global による回避策は、npm キャッシュが空の場合に失敗することがあります。
CLI_MISSING	上記のリンクから公式の Cursor CLI をインストールしてください。標準とは異なる場所にある場合は、CALL_GROKBOT_CURSOR_CLI に実行ファイルの絶対パスを設定してください。
AUTH_REQUIRED または AUTH_EXPIRED	指定された npx のログインコマンドを再度実行し、ブラウザーでのサインインを完了してから、npx --yes https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz doctor を実行してください。MCP の起動時にブラウザーが自動で開くことはありません。
スキルまたは MCP ツールが見つからない	codex plugin list または claude plugin list でプラグインがインストールされ、有効になっていることを確認してから、新しいクライアントセッションを開始してください。MCP のみをインストールしても、スキルは含まれません。
Claude Code でツールを利用できないと表示される、またはサーバーが接続中のままになる	MCP の起動を待ち、claude mcp list を確認してください。ヘルスチェックで接続済みと報告された後もセッションにツールが表示されない場合は、新しいセッションを開いてください。すでに送信された可能性のあるタスクを再送信しないでください。
ボットが見つからない、またはリクエストで 403 が返される	ボット名とサインインしたブラウザーアカウントが正確であることを確認してください。ログインが有効でも、文書化されていないボット RPC を利用できるとは限りません。復旧と制限を参照してください。

既存のプラグインインストールを更新する

以前のタグに固定された Codex マーケットプレイスは、そのタグのままになります。このプラグインのリリースに更新するには、ターミナルで次のコマンドを実行してください。

codex plugin remove call-grokbot@call-grokbot
codex plugin marketplace remove call-grokbot
codex plugin marketplace add ZensHQ/call-grokbot --ref plugin-v0.1.2
codex plugin add call-grokbot@call-grokbot

Claude Code のユーザースコープインストールの場合：

claude plugin marketplace update call-grokbot
claude plugin update call-grokbot@call-grokbot --scope user

更新後、新しいクライアントセッションを開始してください。公式の Cursor CLI ログインはプラグインとは独立して共有されるため、有効であれば再度行う必要はありません。

オプション：MCP を直接設定する

MCP ツール 4 つだけが必要な場合は、プラグインの代わりにこちらを使用してください。同じクライアントに両方の方法をインストールしないでください。ツールが重複して表示されます。この方法には consult は含まれません。通常のプロンプトで、コーディングアシスタントに call-grokbot ツールを使用するよう依頼してください。

まず、同じターミナルログインと doctor チェックを完了してください。

npx --yes https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz login
npx --yes https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz doctor

Codex の場合は、ターミナルからサーバーを登録してください。

codex mcp add call-grokbot -- npx --yes https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz

ボットの許可リストと長時間のタスクを設定するには、~/.codex/config.toml に同じエントリを設定してください。

[mcp_servers.call-grokbot]
command = "npx"
args = ["--yes", "https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz"]
startup_timeout_sec = 30
tool_timeout_sec = 660
env = { CALL_GROKBOT_AGENTS = "Research Bot" }

Claude Code の場合は、ターミナルからサーバーを登録してください。

claude mcp add --transport stdio --scope user call-grokbot -- npx --yes https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz

または、ユーザースコープのエントリの代わりに、信頼できるプロジェクトで次の .mcp.json を使用してください。

{
  "mcpServers": {
    "call-grokbot": {
      "command": "npx",
      "args": ["--yes", "https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz"],
      "env": {
        "CALL_GROKBOT_AUTH_MODE": "browser",
        "CALL_GROKBOT_AGENTS": "Research Bot"
      }
    }
  }
}

Research Bot を、既存の正確な名前に置き換えてください。MCP の設定を変更した後は、新しいクライアントセッションを開いてください。

オプション：グローバルインストールまたはソースからのインストール

グローバルコマンドを使用するには、npm install --global [email protected] をインストールしてください。その後は、指定された npx 形式の代わりに、call-grokbot login、doctor などのサブコマンドを直接使用できます。

ソースから実行するには：

git clone https://github.com/ZensHQ/call-grokbot.git
cd call-grokbot
npm ci
npm run build
node dist/cli.js login
node dist/cli.js doctor

ソースのコマンドには node /absolute/path/to/call-grokbot/dist/cli.js を使用してください。JSON/TOML の MCP 設定では、command を node に、args を ["/absolute/path/to/call-grokbot/dist/cli.js"] に設定してください。

4 つのツール

ツール	目的
list()	アカウントから確認できる既存のボット、任意の許可リスト、ローカルの連絡先を一覧表示します。メッセージは送信しません。
ask({agent, message, wait_seconds})	指定した既存のボットに一度だけ送信します。存在しない名前や曖昧な名前は拒否され、ボットは作成されません。
check({agent, wait_seconds})	未読の返信を読み取り、既存のタスクを待ちます。メッセージを再送信することはありません。
interrupt({agent})	連絡済みのボットの現在のターンを停止します。アプリ内で開始された作業が含まれる場合があります。完了済みの操作は取り消されません。

agent を省略できるのは、許可リストにボットが 1 つだけ含まれている場合です。 wait_seconds のデフォルトは 45 で、0～600 を指定でき、0 の場合は初期スナップショットを返します。結果には status: "running" | "finished" と任意の reply が含まれます。running の場合は check を呼び出してください。ask を繰り返さないでください。 finished と判断するには、最初の確認応答だけでなく、ボットの最新の状態とターン完了の証拠が必要です。中断されたターンは、返信なしで完了する場合があります。

ask の結果には、以前の未読メッセージからの earlierReplies が含まれる場合があります。それらは新しいタスクへの回答とは分けてください。check はローカルのカーソルを進めるため、2 回目の check ではすでに読み取った返信は繰り返されません。カーソル値は、JavaScript の安全な整数範囲を超える場合も含め、10 進文字列のままです。内部のツールステップは返信として返されません。

プロンプトの例：

Research Bot に、添付した 2 つのデプロイ方法を比較するよう依頼してください。この会話にあるレイテンシ測定値と予算の制約も含めてください。 3 つのトレードオフと 1 つの推奨案を求めてください。調査のみを行い、変更は加えないでください。

認証の有効期限とログアウト

npx --yes https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz auth status
npx --yes https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz auth refresh
npx --yes https://registry.npmjs.org/call-grokbot/-/call-grokbot-0.1.1.tgz logout

CURSOR_API_KEY が設定されている場合でも、デフォルトの認証方式は browser です。 ブラウザーが別のコンピューターにある場合は、NO_OPEN_BROWSER=1 を指定してログインを実行すると、公式 CLI にログイン URL を表示させることができます。

auth refresh を実行すると、別の 公式ブラウザーサインイン が開きます。 インストール済みの公式 CLI のブラウザーセッションには固定の有効期間があります（テストで確認したセッションは約 60 日でした）。その refreshToken フィールドは、サイレント更新の仕組みとして検証されていません。このプロジェクトでは、OAuth の更新エンドポイントを独自に作成したり、ブラウザー認証が無期限に無人で継続すると約束したりすることはありません。

認証された各リクエストでは、最新の公式認証情報が読み込まれます。再ログインに成功すると、MCP サーバーを再起動しなくても反映されます。認証情報の有効期限が切れている場合、取り消された場合、または見つからない場合は、ツールが停止して再度サインインするよう通知します。doctor はトークンを表示せずに有効期限を報告します。ask／check も、ブラウザーセッションの有効期限まで 5 分以内になると警告します。ログアウトすると、共有されている公式 Cursor CLI のセッションからサインアウトします。そのログインを使用している他のプログラムも、再度サインインする必要があります。ローカルの連絡先は保持されるため、アカウント固有の読み取りカーソルは再開できます。ログアウトしても、クラウド上のボットの作業は停止せず、完了済みの操作も取り消されません。

任意の明示的な CALL_GROKBOT_AUTH_MODE=api-key モードでは、無人環境での短期トークンの更新をサポートします。CALL_GROKBOT_API_KEY、CURSOR_API_KEY、明示的に指定された CURSOR_API_KEY_FILE、次に CURSOR_SERVICE_ACCOUNT_KEY の順に読み込みます。キーを短期間有効なセッションと交換し、同時に発生する交換を共有し、有効期限前に更新します。また、新しいトークンを取得した場合は、認証済みの 読み取り を 1 回再試行します。テストした個人用キーでは、Sign in to the Cursor CLI and SDK と Run agents の両方が有効になっていました。最小限必要な権限のセットは確認されていません。サービスアカウントから個人用ボットにアクセスできるかは検証されていません。このパッケージがキーを保存することはありません。

設定

変数	デフォルト	説明
CALL_GROKBOT_AUTH_MODE	browser	browser または明示的な api-key
CALL_GROKBOT_CURSOR_CLI	自動検出	公式の agent 実行ファイルへの絶対パス
CALL_GROKBOT_AGENTS	既存のすべてのボット	カンマ区切りの名前、または名前の JSON 配列／{name,description} オブジェクト
CALL_GROKBOT_DEFAULT_WAIT_SECONDS	45	デフォルトのツール待機時間。上限で制限されます
CALL_GROKBOT_MAX_WAIT_SECONDS	600	許可される最大ツール待機時間
CALL_GROKBOT_REQUEST_TIMEOUT_MS	20000	単項 HTTP リクエストごとのタイムアウト
CALL_GROKBOT_SETTLE_MS	1500	完了確認後の静穏期間
CALL_GROKBOT_DISABLED_TOOLS	空	除外するツール名をカンマ区切りで指定します
CALL_GROKBOT_STATE_DIR	OS の状態ディレクトリ	ローカルの連絡先情報とプロセス間ロック
CALL_GROKBOT_API_BASE_URL	https://api2.cursor.sh	公式オリジンまたはループバックテストサーバー。他のホストは拒否されます

デフォルトの状態ディレクトリは、$XDG_STATE_HOME/call-grokbot または ~/.local/state/call-grokbot です。Windows では %LOCALAPPDATA%/call-grokbot です。 状態には、ボット識別子、カーソル、タイムスタンプ、保留中のメッセージ受信情報のみが含まれます。認証済みのサブジェクトとオリジンごとに分離されます。POSIX ではファイルの権限が 0600、ディレクトリの権限が 0700 です。Windows ではユーザープロファイルの ACL に従います。 生のトークン、キー、会話のテキスト、ブラウザーの Cookie がここに保存されることはありません。

復旧と制限事項

• 送信未確認： メッセージ ID は送信前に保存されます。check を使って配信状況と返信を確認してください。タイムアウトや HTTP 5xx の後も、メッセージや割り込みが自動再試行されることはありません。確認せずに再送しないでください。
• キャンセル／ストリームエラー： 未読カーソルは保持されます。メッセージが送信済みの場合、その保留中の受信情報は保持され、check で処理を再開できます。
• タスク保留中： check で完了が確認されるまで、2 回目の ask は拒否されます。ボットごとのファイルロックにより、複数のローカルクライアントが送信を交互に行うことも防止されます。
• 状態破損またはトランスクリプトのリセット： フェイルクローズします。実際の会話を確認してから、state.json をバックアップし、影響を受けた連絡先を解決してください。
• 権限エラー 403： ログインが有効でも、この非公開 RPC にアクセスできるとは限りません。別のアカウントの使用、ボットの作成、権限の拡大は試みません。

これらのツールは、アカウントに紐づく実際のボットとの会話を操作します。コードやテキストを含めない限り、ボットは IDE のコンテキストを参照できません。含めたコードやテキストは、お使いのマシンからサービスに送信されます。ボットの返信には、信頼できない外部情報が含まれる場合があります。許可リストが制限するのはこのクライアントであり、ログインアカウントの権限ではありません。 ブラウザーのデバッグポート、保存済みブラウザー Cookie の抽出、HTTP/SSE リスナー、承認の回避、Grok モデルのサブスクリプションプロキシは使用しません。

開発とテスト

npm ci
npm run check
npm test
npm run typecheck
npm run test:plugins
npm pack --dry-run

test:plugins は新しい匿名 npm キャッシュを使用して、固定された公開ランタイムをダウンロードし、このソースチェックアウト、無関係なプロジェクト、同じ名前／同じバージョンのフィクスチャから、両方のプラグインランチャーをテストします。認証やボットへのメッセージ送信を行わずに、4 つすべてのツールを検出します。ネットワークアクセスが必要で、CI でも実行されます。

テストでは、認証情報のローテーション、期限切れ／ログアウト、API キー更新の同時実行、アカウント分離、大きなカーソル、分割された Connect フレーム、読み取りの再試行、書き込みの非再試行、送信保留からの復旧、キャンセル、プロセス間の状態書き込み、待機中の ask に対する割り込み、MCP の検出／スキーマ／呼び出しを検証します。

既存の専用ボットに対して実際のテストを任意で実行するには：

CALL_GROKBOT_LIVE_AGENT="Your Test Bot" npm run test:live

実際の PONG メッセージを送信し、増分読み取りと完了確認を検証した後、完了後に interrupt を呼び出します。ボットのプロフィールは変更しません。ライブテストの成果物は gitignore 対象で、認証情報は含まれません。テスト対象範囲の詳細については、検証に関する注記を参照してください。

Zens AI 提供。MIT。独立した実装と参考資料については、NOTICE.mdを参照してください。