Call Grok Bot

call-grokbot

在 Codex 和 Claude Code 中向现有的 Grok Bots 提问。本地 stdio MCP 服务会发送一个独立任务、读取增量回复，并可中断已联系的机器人。你的机器人会保留现有对话、 记忆和已连接的工具。

非官方项目。与 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 账户，并至少有一个现有机器人。请使用应用中显示的准确机器人名称； 此软件包不会创建机器人。

选择 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 替换为你的 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.

这会向该 Bot 现有的对话发送一条真实消息。只有在收到 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

在交互式安装面板中，选择 为你安装（用户级作用域）。 有关其他安装作用域，请参阅Claude Code 官方插件文档。

2. 在终端中登录 Bot 账户

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

使用拥有你 Bot 的账户，通过官方 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.

这会在你的 Bot 对话中发送一条真实消息。请确认 PONG 和 finished 均已出现。对于日常工作，请在简报中提供相关内容：Bot 无法自动查看你的 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 工具，可以使用此方式代替插件。不要在同一个客户端中同时安装这两种方式，否则会出现重复工具。此方式不包含 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]。 之后，你可以直接使用 call-grokbot login、doctor 和其他子命令，而不必使用固定的 npx 形式。

如需从源代码运行：

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"]。

四个工具

工具	用途
list()	列出账号可见的现有机器人、可选允许列表和本地联系人。不发送消息。
ask({agent, message, wait_seconds})	向一个确切存在的机器人发送一次消息。不存在或名称不明确时会拒绝；不会创建机器人。
check({agent, wait_seconds})	读取未读回复，并等待现有任务。绝不会重新发送消息。
interrupt({agent})	停止已联系机器人的当前轮次。它可能包含在应用中已开始的工作；已完成的操作不会撤销。

仅当允许列表中只有一个机器人时，agent 才可以省略。 wait_seconds 默认为 45，接受 0–600，设为零时返回初始 快照。结果包含 status: "running" | "finished" 和可选的 reply。running 表示应调用 check；不要重复调用 ask。 finished 需要依据机器人的实时状态和轮次完成证据，不能只看首次确认。 被中断的轮次可能会在没有回复的情况下结束。

ask 的结果可能包含来自先前未读消息的 earlierReplies；请将它们与 新任务的回答分开。check 会推进本地游标，因此第二次调用 check 不会重复 已读取的回复。游标值始终是十进制字符串，包括超出 JavaScript 安全整数 范围的值。内部工具步骤不会作为回复返回。

提示词示例：

请让 Research Bot 比较附带的两种部署方案。请纳入本次对话中的 延迟测量数据和预算限制。要求列出三项权衡和一项建议。仅做研究；不要进行任何更改。

身份验证过期与注销

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

默认身份验证方式为 browser，即使设置了 CURSOR_API_KEY 也是如此。 如果浏览器位于另一台计算机上，请使用 NO_OPEN_BROWSER=1 运行登录命令， 以便官方 CLI 显示登录 URL。

auth refresh 会打开另一个官方浏览器登录页面。已安装的官方 CLI 浏览器会话具有固定的有效期（测试中观察到的会话约为 60 天）；其 refreshToken 字段并非经过验证的静默刷新机制。本项目不会自行实现 OAuth 刷新端点，也不会承诺浏览器身份验证可以无限期无人值守地使用。

每次经过身份验证的请求都会读取最新的官方凭据。重新登录成功后，无需重启 MCP 服务 即可使用新凭据。凭据过期、被撤销或缺失时，工具会停止运行并提示你重新登录。doctor 会报告过期情况，但不会显示令牌；若浏览器会话将在五分钟内过期，ask/check 也会发出 警告。注销会退出共享的官方 Cursor CLI 会话；其他使用该登录状态的程序也必须 重新登录。本地联系人会保留，因此可以继续使用账号专属的读取游标。 注销不会停止云端机器人的工作，也不会撤销已完成的操作。

可选的显式 CALL_GROKBOT_AUTH_MODE=api-key 模式支持短期令牌的无人值守续期。它会按顺序 读取 CALL_GROKBOT_API_KEY、CURSOR_API_KEY、显式指定的 CURSOR_API_KEY_FILE，然后读取 CURSOR_SERVICE_ACCOUNT_KEY。它会用密钥 换取短期会话、共享并发换取操作、在到期前续期，并在获得新令牌后对经过身份验证的读取 操作重试一次。经过测试的个人密钥同时启用了 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	所有现有机器人	以逗号分隔的名称，或由名称 / {name,description} 对象组成的 JSON 数组
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	操作系统状态目录	本地联系人和跨进程锁
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 观察到任务完成之前，会拒绝第二次 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 缓存，下载固定版本的公开运行时，并在此源码检出目录、无关项目和同名 / 同版本测试样例中检查两个插件启动器。它会发现全部四个工具，但不会进行身份验证或发送机器人消息。此测试需要网络访问，也会在 CI 中运行。

测试涵盖凭据轮换、过期 / 登出、API 密钥续期并发、账号隔离、大游标、分片 Connect 帧、读取重试、不重试写入、待发送消息恢复、取消、跨进程状态写入、等待中的 ask 遇到中断，以及 MCP 发现 / 架构 / 调用。

如需选择性地对专用的现有机器人运行真实测试：

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

此测试会发送一条真实的 PONG 消息，验证增量读取和已确认完成，并在完成后调用 interrupt。它绝不会修改机器人资料。实时测试产物会被 gitignore 忽略，且不包含任何凭据。有关精确测试边界，请参阅验证说明。

由 Zens AI 提供。MIT。有关独立实现和参考资料，请参阅 NOTICE.md。