有许多编码代理。这个由 Grok 提供支持。

其余部分则互相借鉴。我们从所有这些项目中汲取灵感，然后将其与Grok连接起来——实时X 搜索、网页搜索、grok-code-fast-1 以及完整的 Grok 模型系列，默认启用子代理，通过 Telegram 远程控制（只需配对一次，即可在 CLI 运行时通过手机操控代理），还有一个不会让人觉得仓促拼凑而成的终端 UI。

开源。原生终端。使用 Bun 和 OpenTUI 构建。如果你既想要氛围感又追求速度，那么你来对了仓库。

社区共建且非官方。本项目与 xAI 无任何关联，也未获得其认可，并非官方的 Grok CLI。

https://github.com/user-attachments/assets/7ca4f6df-50ca-4e9c-91b2-d4abad5c66cb

---

安装

curl -fsSL https://raw.githubusercontent.com/superagent-ai/grok-cli/main/install.sh | bash

替代安装方式（需要将 Bun 添加到 PATH）：

bun add -g grok-dev

自我管理（仅限脚本安装）：

grok update
grok uninstall
grok uninstall --dry-run
grok uninstall --keep-config

先决条件： 一个来自 x.ai 的 Grok API 密钥，以及用于交互式 OpenTUI 体验的现代终端模拟器。无头 --prompt 模式并不依赖于终端 UI 支持。如果你想通过内置的计算机子代理实现主机桌面自动化，还请在 macOS 上为你的终端应用启用 辅助功能 权限。

---

运行它

交互式（默认） — 启动 OpenTUI 编码代理：

grok

支持的终端

为了获得最可靠的交互式 OpenTUI 体验，请使用现代终端模拟器。目前我们记录并推荐以下几种：

• WezTerm（跨平台）
• Alacritty（跨平台）
• Ghostty（macOS 和 Linux）
• Kitty（macOS 和 Linux）

其他现代终端也可能适用，但这些是我们目前推荐并记录用于交互式使用的终端应用。

选择项目目录：

grok -d /path/to/your/repo

无头模式 — 一个提示后退出（脚本、CI、自动化）：

grok --prompt "运行测试套件并总结失败"
grok -p "给我看看 package.json" --directory /path/to/project
grok --prompt "重构 X" --max-tool-rounds 30
grok --prompt "总结仓库状态" --format json
grok --prompt "整夜审查仓库" --batch-api
grok --verify

--batch-api 使用 xAI 的批量 API，以更低的成本进行无人值守的运行。它非常适合脚本、CI、定时任务以及其他不需要即时结果的非交互式工作流。

继续已保存的会话：

grok --session latest
grok -s <session-id>

同样适用于交互式模式——使用相同的标志。

结构化无头输出：

grok --prompt "总结仓库状态" --format json

--format json 会输出以换行符分隔的 JSON 事件流，而不是默认的人类可读文本输出。这些事件是语义化的步骤级记录，例如 step_start、text、tool_use、step_finish 和 error。

计算机子代理

Grok 自带一个由 [agent-desktop](https://github.com/lahfir/agent-desktop) 支持的内置 **computer** 子代理，用于在 macOS 上实现主机桌面自动化。

你可以用自然语言请求它，例如：

grok "使用计算机子代理截取我的主机桌面截图，并告诉我当前打开了哪些内容。"
grok "使用计算机子代理打开 Google Chrome，拍摄界面快照，并告诉我地址栏和标签页分别对应哪些引用。"

注意事项：

• 截图默认保存在 **.grok/computer/** 目录下。
• 主要的工作流程是 截图 -> 引用 -> 操作 -> 截图，利用 agent-desktop 的辅助功能截图和稳定的引用，如 @e1。
• computer_screenshot 可用于视觉确认，但更推荐的方式是使用 computer_snapshot 结合基于引用的操作，如 computer_click、computer_type 和 computer_scroll。
• 在 macOS 上，终端应用运行 grok 时需要 系统设置 → 隐私与安全性 → 辅助功能 的访问权限。
• agent-desktop 目前仅支持 macOS。
• 如果在安装过程中 Bun 阻止了原生二进制文件的下载，请运行：

node ./node_modules/agent-desktop/scripts/postinstall.js

定时任务

定时任务可以让 Grok 按照固定的时间表或一次性地运行无头提示。你可以用自然语言来请求，例如：

创建一个名为 daily-changelog-update 的定时任务，每周工作日早上 9 点运行，
并根据最新的合并提交更新 CHANGELOG.md 文件。

重复性的定时任务需要后台守护进程：

grok daemon --background

在 TUI 中使用 /schedule 可以浏览已保存的定时任务。一次性任务会立即在后台开始执行；而重复性任务则会在守护进程保持运行期间持续执行。

列出 Grok 模型及定价提示：

grok models

无需额外提示直接传递开场白：

grok 修复 src/foo.test.ts 中的不稳定测试

从聊天中生成图片或短视频：

grok "为我的名为 Grok Forge 的命令行工具设计一个复古未来主义的 logo"
grok "将 ./assets/hero.png 编辑成一幅水彩海报"
grok "将 ./assets/cover.jpg 动画化为一段 6 秒的电影级推入镜头"

图像和视频生成作为代理工具嵌入到正常的聊天会话中。你会继续使用文本模型进行会话，而生成的媒体默认会保存在 .grok/generated-media/ 目录下，除非你指定了特定的输出路径。

---

你实际能获得的内容

项目	含义
Grok原生	针对Grok优化的默认配置；包括诸如**grok-code-fast-1**、**grok-4-1-fast-reasoning**、**grok-4.20-multi-agent-0309**等模型，以及旗舰版和快速版——运行grok models即可查看完整列表。
X + 网络搜索	**search_x** 和 **search_web** 工具——实时获取帖子和文档，无需假装互联网停留在2023年。
媒体生成	内置的**generate_image** 和 **generate_video** 工具，支持文生图、图像编辑、文生视频和图生视频流程。生成的文件会本地保存，以便在xAI URL失效后仍可重复使用。
子代理（默认行为）	前台**task**委派（例如探索、通用或计算机任务），加上后台**delegate**用于只读深度分析——真正实现并行化操作。
验证	**/verify** 或 **--verify** — 检查你的应用，构建、测试、启动，并在沙盒环境中运行浏览器冒烟测试。包含截图和视频。
计算机使用	内置的**computer**子代理，通过**agent-desktop**实现主机桌面自动化。它优先使用语义化的无障碍快照和稳定引用，必要时会在**.grok/computer/**目录下保存截图。
自定义子代理	在**~/.grok/user-settings.json**中使用**subAgents**定义命名代理，并通过TUI中的**/agents**进行管理。
远程控制	从TUI配对Telegram（/remote-control → Telegram）：向机器人发送私信，输入**/pair**，并在终端确认代码。保持CLI运行，同时可用手机与之交互。
无“隐藏式”界面	OpenTUI React终端界面——快速、键盘驱动，绝非你想象中的那些卡顿工具。
技能	代理技能位于**.agents/skills/<name>/SKILL.md**（项目级）或**~/.agents/skills/**（用户级）。使用TUI中的**/skills**可列出已安装的技能。
MCPs	可通过模型上下文协议服务器扩展功能——可通过TUI中的**/mcps**或**.grok/settings.json**（mcpServers）进行配置。
会话	对话状态持久保留；**--session latest**会从上次中断的地方继续。
无头模式	使用**--prompt** / **-p**进行非交互式运行——可管道处理、脚本化或基准测试。
可 hack	TypeScript、清晰的代理循环、以Bash为主的工具——随意fork，大胆使用。

即将推出

更深入的自主代理测试 — 持久化的沙盒会话、更丰富的浏览器工作流，以及更强有力的“证明其有效”的证据。

---

API密钥（任选其一）

环境变量（适合CI）：

export GROK_API_KEY=your_key_here

项目中的**.env**文件（如有.env.example，请参考）：

GROK_API_KEY=your_key_here

CLI一次性设置：

grok -k your_key_here

保存在用户设置中 — ~/.grok/user-settings.json：

{ "apiKey": "your_key_here" }

可选的**subAgents**——自定义前台子代理。每个条目需包含**name**、**model**和**instruction**：

{
  "subAgents": [
    {
      "name": "security-review",
      "model": "grok-code-fast-1",
      "instruction": "优先考虑安全影响，并提出具体的修复建议。"
    }
  ]
}

代理名称不能为general、explore、vision、verify或computer，因为这些名称已被内置子代理预留。

可选：**GROK_BASE_URL**（默认https://api.x.ai/v1）、**GROK_MODEL**、**GROK_MAX_TOKENS**。

---

Telegram（远程控制）——简要说明

1. 使用@BotFather创建一个机器人，复制令牌。
2. 设置**TELEGRAM_BOT_TOKEN**，或将**telegram.botToken**添加到~/.grok/user-settings.json中（TUI中的**/remote-control**流程也可保存）。
3. 启动**grok**，必要时打开**/remote-control** → Telegram，然后在Telegram中向机器人发送私信：`/pair``，并在终端提示时输入6位字符代码**。
4. 第一位用户需要手动批准一次，之后系统会记住该用户。请保持CLI进程运行，以便持续使用机器人（长轮询功能依赖于该进程）。

语音与音频消息

在 Telegram 中发送语音消息或音频附件，Grok 会使用 whisper.cpp 在本地将其转录为文本，然后再将文本传递给代理。整个过程不涉及任何云端的语音识别服务——一切都在你的设备上运行。

前置条件

依赖项	作用	安装（macOS）
whisper-cli	执行实际的语音转文本推理	brew install whisper-cpp
ffmpeg	将 Telegram 的语音消息（OGG/Opus 格式）转换为 whisper.cpp 可接受的 WAV 格式	brew install ffmpeg

安装完成后，请验证两者是否可用：

whisper-cli -h
ffmpeg -version

下载 Whisper 模型

Grok CLI 会在首次使用时自动下载配置的模型，但你也可以提前下载：

mkdir -p ~/.grok/models/stt/whisper.cpp
curl -L https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin \
  -o ~/.grok/models/stt/whisper.cpp/ggml-tiny.en.bin

可用的模型（大小与准确率成反比）：tiny.en（75 MB）、base.en（142 MB）、small.en（466 MB）。

在 ~/.grok/user-settings.json 中配置

{
  "telegram": {
    "botToken": "YOUR_BOT_TOKEN",
    "audioInput": {
      "enabled": true,
      "binaryPath": "/opt/homebrew/bin/whisper-cli",
      "model": "tiny.en",
      "modelPath": "~/.grok/models/stt/whisper.cpp/ggml-tiny.en.bin",
      "autoDownloadModel": true,
      "language": "en"
    }
  }
}

设置	默认值	描述
enabled	true	设置为 false 可以完全忽略语音/音频消息。
binaryPath	whisper-cli	whisper.cpp CLI 二进制文件的绝对路径或命令名。
model	tiny.en	用于自动下载解析的模型别名。
modelPath	(自动解析)	显式指定 .bin 模型文件的路径。会覆盖 model 和自动下载设置。
autoDownloadModel	true	在首次使用时将模型下载到 ~/.grok/models/stt/whisper.cpp 目录中。
language	en	传递给 CLI 的 Whisper 语言代码。

如果你不想打开 TUI 界面，可以使用无头模式：

grok telegram-bridge

请将机器人令牌视为密码。

---

钩子

钩子可以在代理生命周期的关键事件触发时执行 Shell 命令——例如强制执行策略、运行代码检查工具、触发测试或记录活动。

在 ~/.grok/user-settings.json 中进行配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/lint-before-edit.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

钩子命令会从 stdin 接收 JSON 数据（包含事件详情），并可以从 stdout 返回 JSON 数据。退出码 0 表示成功，2 表示阻止操作，其他值表示非阻塞错误。

支持的事件： PreToolUse、PostToolUse、PostToolUseFailure、UserPromptSubmit、SessionStart、SessionEnd、Stop、StopFailure、SubagentStart、SubagentStop、TaskCreated、TaskCompleted、PreCompact、PostCompact、Notification、InstructionsLoaded、CwdChanged。

---

指令与项目知识库

• **AGENTS.md** — 从 Git 仓库根目录合并到当前工作目录的内容（类似 Codex 风格；详见仓库文档）。如果某个目录下存在 **AGENTS.override.md** 文件，则优先使用该文件。

---

项目设置

项目文件：**.grok/settings.json** — 例如，用于指定该项目使用的模型。

---

沙盒

Grok CLI 可以在 Shuru 微虚拟机沙盒中运行 Shell 命令，从而确保代理无法访问宿主机的文件系统或网络。

需要 macOS 14+ 且搭载 Apple Silicon 芯片。

通过命令行参数 --sandbox 启用，或者在 TUI 中使用 /sandbox 切换。

当沙盒模式启用时，你可以配置以下内容：

• 网络 — 默认关闭；可通过 --allow-net 开启，并使用 --allow-host 进行限制。
• 端口转发 — --port 8080:80
• 资源限制 — CPU、内存、磁盘空间（可通过设置或 /sandbox 面板调整）。
• 检查点 — 从保存的环境快照启动。
• 密钥 — 注入 API 密钥，而无需在虚拟机内部暴露它们。

所有设置都会保存在 ~/.grok/user-settings.json（用户级）和 .grok/settings.json（项目级）中。

验证

在 TUI 中运行 **/verify** 或在命令行中使用 **--verify** 来本地验证你的应用：

grok --verify
grok -d /path/to/your/app --verify

代理会检查你的项目，确定如何构建和运行它，然后启动一个沙盒环境，并生成包含截图和视频证据的验证报告。适用于任何类型的应用程序。

---

开发

从克隆的代码库开始：

bun install
bun run build
bun run start
# 或：node dist/index.js

其他常用命令：

bun run dev      # 从源代码运行（Bun）
bun run typecheck
bun run lint

---

许可证

MIT

grok-cli 快速上手指南

grok-cli 是一个基于 Grok 模型的开源终端 AI 编程助手。它集成了实时 X (Twitter) 搜索、网页搜索、多智能体协作、桌面自动化控制以及 Telegram 远程控制等功能，专为追求高效开发的开发者设计。

环境准备

在开始之前，请确保满足以下前置条件：

• 操作系统：支持 macOS、Linux 及 Windows（推荐现代终端模拟器）。
• 终端模拟器：为获得最佳的交互式界面 (OpenTUI) 体验，推荐使用以下终端之一：
  • WezTerm (跨平台)
  • Alacritty (跨平台)
  • Ghostty (macOS/Linux)
  • Kitty (macOS/Linux)
• API Key：需要从 x.ai 获取有效的 Grok API Key。
• 权限配置 (macOS 用户)：若需使用内置的“电脑子智能体”进行桌面自动化操作，需在 系统设置 -> 隐私与安全性 -> 辅助功能 中授予终端应用权限。

安装步骤

方法一：一键脚本安装（推荐）

运行以下命令自动下载并安装：

curl -fsSL https://raw.githubusercontent.com/superagent-ai/grok-cli/main/install.sh | bash

方法二：通过 Bun 安装

如果你已安装 Bun 且将其加入环境变量，可使用以下命令：

bun add -g grok-dev

验证与管理

安装完成后，可使用以下命令管理工具：

grok update        # 更新版本
grok uninstall     # 卸载

基本使用

1. 配置 API Key

使用前需配置密钥，任选一种方式即可：

• 环境变量（推荐用于 CI/CD）：

  export GROK_API_KEY=your_key_here
  

• 项目本地配置： 在项目根目录创建 .env 文件：

  GROK_API_KEY=your_key_here
  

• 命令行一次性配置：

  grok -k your_key_here
  

• 全局配置文件： 编辑 ~/.grok/user-settings.json：

  { "apiKey": "your_key_here" }
  

2. 启动交互式模式

进入你的项目目录，直接运行 grok 启动带有图形界面的终端助手：

cd /path/to/your/repo
grok

你也可以指定工作目录启动：

grok -d /path/to/your/repo

3. 无头模式 (Headless)

适用于脚本、CI 流程或单次任务执行，执行完毕后自动退出：

# 执行测试并总结失败原因
grok --prompt "run the test suite and summarize failures"

# 查看特定文件
grok -p "show me package.json" --directory /path/to/project

# 限制工具调用轮次
grok --prompt "refactor X" --max-tool-rounds 30

# 输出 JSON 格式结果（便于程序处理）
grok --prompt "summarize the repo state" --format json

4. 高级功能示例

• 桌面自动化 (Computer Sub-agent)： 让 Grok 控制你的桌面（需 macOS 辅助功能权限）：

  grok "Use the computer sub-agent to take a screenshot of my host desktop and tell me what is open."
  

• 生成图片/视频： 直接在对话中请求生成媒体文件：

  grok "Generate a retro-futuristic logo for my CLI called Grok Forge"
  grok "Animate ./assets/cover.jpg into a 6 second cinematic push-in"
  

  生成的文件默认保存在 .grok/generated-media/ 目录下。

• 恢复会话： 继续上一次的对话上下文：

  grok --session latest
  

• 模型列表查询： 查看当前支持的 Grok 模型及定价提示：

  grok models