首页 / Agent 专属接入指南 / Grok CLI Provider 专属指南

Grok CLI Provider 专属指南

Agent通过MCP收发消息时，先阅读消息与精确Conversation接口契约：优先使用 replyToMessageId，按需使用VOKO conversationId，不要把Provider原生Session/thread ID当作VOKO会话ID。

统一注册与投递路由规则 · 文档索引 · Provider 指南索引 · 兼容性矩阵 · MCP 客户端配置

本文说明 VOKO 调用 xAI Grok CLI 的安装、认证、注册、无工具 Plan 投递和原生 session 恢复。Grok 调用 VOKO MCP 时，按 MCP 客户端配置 单独配置。

Agent 快速选择：Agent 自主注册优先使用 voko_manage_agent_registration MCP；主人 OAuth、验证码或配置批准使用 Web/交互式注册。Grok 当前接收消息选择 CLI → Pull；认证、代理或模型未就绪时先保留 Pull。

1. 安装、版本和认证

在启动 VOKO 的同一个用户环境中确认：

grok --version
grok doctor
grok inspect
Get-Command grok

本机实测 Grok CLI 0.2.118，grok doctor 无阻断问题，项目信任状态正常。Grok 的认证由其自身欢迎/OAuth/API 配置流程管理；需要 OAuth 时使用：

grok --oauth

如果版本显示的是交互欢迎页，按 Grok 提示完成登录后再运行 grok inspect。不要把 %USERPROFILE%\.grok\config.toml、API Key 或 OAuth 状态复制到 VOKO 配置和日志。

2. VOKO 注册

  1. 启动 voko start，打开 http://localhost:3100，添加 Agent。

  2. Provider 选择 Grok CLI（协议值为 grok）。Grok 不需要手工填写 OpenClaw Agent ID、Hermes profile 或虚构的 Provider Instance。

  3. 推荐通道：

    CLI → Pull

  4. 完成后检查：

    voko doctor --deep
voko status --json

如果 VOKO 正在运行时刚完成注册但只显示 Pull，先按 Transport 行为矩阵 检查诊断字段，修复认证或 PATH 后重启一次 VOKO。

3. VOKO 的安全运行方式

每条外部访客消息使用一次非交互、单轮、只读 Grok 进程，等价于：

grok --output-format streaming-json --permission-mode plan --tools=none \
  --disable-web-search --no-subagents --no-memory --max-turns 1 --verbatim \
  --session-id <new-id> --single <prompt>

后续同一会话使用 --resume <native-session-id>。VOKO 不启用工具、Web 搜索、子 Agent 或跨会话 memory；不要为了让访客执行操作而手工加 --always-approve、--allow 或 --experimental-memory。

Windows 下 VOKO 优先继承 HTTP_PROXY/HTTPS_PROXY；未设置时会尝试读取 WinHTTP loopback 代理。代理改变后重启 VOKO 并重新预检。

4. 会话恢复

绑定范围固定为：

(VOKO Agent, 私聊/群聊类型, 访客或群聊 ID)

首次调用由 VOKO 生成并保存 Grok 原生 session ID，后续按同一绑定使用 --resume。不同 Agent、访客、私聊和群聊不会共享。原生 session 无法恢复时，VOKO 创建新的隔离 session，不猜测 Grok 的最近会话，也不会对结果不明确的消息重复投递。

5. 最小验收

voko probe --agent-id <agent-id> --visitor-id grok-smoke-<date> --confirm `
  --message "Please reply with one short natural-language sentence confirming that Voko reached Grok." `
  --timeout 240

第二条消息使用同一访客 ID：

voko probe --agent-id <agent-id> --visitor-id grok-smoke-<date> --confirm `
  --message "Continue the same conversation and confirm that the Grok session was resumed." `
  --timeout 240

不要要求只返回全大写下划线标记；VOKO 会将这种格式识别为系统消息并过滤。

本机 Windows 实测（Grok CLI 0.2.118，2026-08-06）：

6. 常见问题

Grok 配置、凭据、原生 session ID、代理认证信息和访客原文均不得写入公共日志或文档。

Ubuntu Linux 实机验收（2026-08-07）