grok-app：实践指南

作者：袖梨 2026-08-21

工作中遇到相关需求时，grok-app值得先读说明，因为它主要用于Grok Build CLI 的桌面工作台 — 会话、项目、媒体、自动化（Tauri 2·非官方）。对软件开发任务来说，依赖、接口和异常处理往往比主路径更影响采用往往决定它能否落地，不能只用安装成功来判断。落地前可以在隔离分支完成一个可回滚的小任务，用安装步骤、接口契约、测试结果和错误信息判断它是否真的省事。我的判断是，它更适合需要可检查开发流程而非单次演示的工程师；若眼下没有这类需求，先保留观察即可。

RongleCat/grok-app 项目截图 1

Grok App

Desktop 本地 Grok Build

工作台

Sessions、项目、媒体、自动化 — 真正的 grok CLI

[!NOTE]

Note

Grok App 不是官方 xAI 产品。 它将本地 Grok Build CLI (grok agent stdio) 包装到桌面工作台中：会话、项目、权限、媒体预览和计划任务。

真正的代理能力需要安装并登录可用的 Grok Build CLI。如果没有 CLI，您可以从首次运行向导进行安装，或使用 GROK_APP_ACP=mock 进行 UI-only 开发。

内容

  1. 概述
  2. 特点
  3. 截图
  4. 安装并首次运行
  5. macOS“损坏”/网守
  6. Linux blank/black 窗口 (WebKit)
  7. Linux 沙箱/用户命名空间 (Ubuntu 24.04+)
  8. 配置路径
  9. 开发和构建
  10. 文档和贡献
  11. 贡献者
  12. 关注作者

概述

grok CLI 是一款功能强大的终端。日常工作仍然需要多项目会话、权限栏、丰富的预览、预定作业和多语言 UI。

Grok App 是那个工作台：

  1. 安装应用程序并准备 Grok Build CLI
  2. 添加项目/新会话
  3. 连接代理；在 Ask 或 YOLO 下聊天
  4. 在“设置”中预览工件、安排自动化、管理帐户和中继

堆栈： Tauri 2 + Rust · React + TypeScript + Vite · Tailwind CSS

特点

面积 你得到什么
真实构建会话 默认grok agent stdio（ACP）；主机拥有的会话 FSM；可选远程 ACP
项目和会议 可信目录、虚拟侧边栏、存档/孤儿、分叉和倒带； 导入/打开CLI会话（独立模式下路径清晰）
多会话流 切换聊天后保持忙碌状态；进程限制和闲置回收
Git 工作树 项目芯片列出链接的工作树；一键切换cwd（非git隐藏）
权限 默认询问；允许一次/会话/拒绝； YOLO; 每个项目权限层
计划/目标 粘性执行进度；资源窗格 Markdown 审查 + 步骤；目标输入
斜线·扩展 斜线调色板，技能；设置 → MCP 扩展 / 插件
作曲家 忙时跟进发送队列；粘贴屏幕截图；上下文使用芯片
媒体和文件 图片/视频/PDF/Office/代码预览； 编辑并保存资源中的文本；更改（会话差异 + 工作区 git）
代理运行时间 失速取消；结构化错误甲板； 诊断 zip 导出； tools/permissions 打开时没有提前“准备好”
自动化 预定清单；自然语言从聊天创建（无声栅栏，UI 中没有 JSON）
账户及额度 多账户切换、官方登录、SuperGrok配额+热图、自定义提供商本地使用
定制继电器 独立的 GROK_HOME 代理配置文件（在需要时保持 ~/.grok 清洁）
安全 可选 OS 钥匙串，用于 API 钥匙（默认 secrets.json 0600）；存储写锁；仅在应用内确认
国际化 简体中文/繁体中文/英文/俄文+托盘
包装 macOS ARM / Intel · Windows x64（安装+便携式） · Linux x64（AppImage / deb / rpm）

截图

来自当前的macOS开发构建。

工作台·SuperGrok 账户及额度
浅色主题 会议及媒体

安装并首次运行

1. 下载

从 版本 获取安装程序：

平台 神器
macOS 苹果芯片 Grok_*_aarch64.dmg
macOS 英特尔 Grok_*_x64.dmg
Windows x64 <em>-setup.exe 安装程序 + </em>-portable.zip
Linux x64 AppImage / .deb / .rpm

捆绑产品名称是 Grok （与窗口标题匹配）。

Arch / Manjaro / EndeavourOS： AppImage 与发行版无关（然后运行 chmod +x）。 CI官方没有发布单独的AUR包。在 Wayland (e.g.Hyprland) + AMD 上，一些主机使用库存 AppImage 进入黑窗 — 更喜欢 .deb / .rpm （系统 WebKit）或Linux blank/black 窗口 解决方法。

预构建的包不需要构建工具。 仅当您从源 构建 [时才需要 Node / pnpm / Rust - 不要只是为了使用该应用程序而运行 pnpm install && tauri build。

验证您的下载

每个版本都会附带一个 SHA256SUMS 文件。下载后：

# macOS / Linux
shasum -a 256 -c SHA256SUMS --ignore-missing
# Windows (PowerShell)
Get-FileHash .Grok_*_x64-setup.exe -Algorithm SHA256

将 PowerShell 哈希值与 SHA256SUMS 中的匹配行进行比较。

Windows SmartScreen

社区/未签名的 Windows 版本在首次运行时显示 SmartScreen “Windows 保护了您的 PC / 未知发布者” — 单击 更多信息 → 仍然运行，如有疑问，请验证上面的校验和。配置 WINDOWS_CERTIFICATE + WINDOWS_CERTIFICATE_PASSWORD 密钥时，发布 CI 可以对安装程序进行 Authenticode 签名（请参阅 docs/BUILD.md）；签名版本使用证书上的发布者名称。

应用内自动更新

设置→关于中的静默更新仅适用于签名的生产版本（Tauri更新程序密钥嵌入+匹配滚动版本上的签名存档）。未签名的社区版本、本地 pnpm dev / 调试二进制文件和某些包类型（e.g。Linux 上的非 AppImage）保留在 GitHub 开放发布/下载安装程序 路径上 - 它们不会收到无提示的应用内更新。完整矩阵和维护人员清单：docs/desktop-auto-update.md。

2. 首次运行

  1. 启动 → 安装向导 确保安装 CLI（支持多镜像安装）
  2. （可选）官方登录/API 密钥/自定义中继 — 可跳过。如果您本地的 grok CLI 已登录，请选择 使用现有的 CLI 登录 — 无需重新授权
  3. 添加项目 → 信任文件夹
  4. 连接客服人员 → 准备好后聊天
  5. 权限栏默认为询问；仅当您需要无人值守运行时才使用 YOLO

三、要求

  • 本地 Grok 构建 CLI (grok) 0.2.112 或更新版本，通常是 ~/.grok/bin/grok 或 PATH - 较旧的 CLIs 拒绝应用程序依赖的标志（之后运行一次 grok update安装，然后完全重新启动应用程序）
  • Windows：%USERPROFILE%.grokbingrok.exe 或 PATH； WebView2 运行时（预装在 Windows 11 上；安装程序会以其他方式引导它）

4. 受限网络（e.g.中国大陆）

Grok 后端 (auth.x.ai / grok.com / cli-chat-proxy.grok.com) 可能无法通过直接连接访问。如果登录挂起或每条消息都超时并显示 NETWORK_PROVIDER：

  1. 设置→运行时→网络：设置代理（系统/手动，e.g.http://127.0.0.1:7890），然后使用测试连接来验证所有三个端点
  2. 优先选择 系统 HTTP 或 手动 http://127.0.0.1:7890（冲突/浪涌混合端口）而不是 TUN。该应用程序解析环回 PAC 并将 HTTP_PROXY 注入代理进程 - 仅当没有其他东西可以路由流量时才需要 TUN
  3. 如果您的 grok CLI 已登录，请通过设置向导重新使用它（或将会话数据模式切换为共享），而不是浏览器 OAuth
  4. 不需要启动器脚本或手动导出的 HTTP_PROXY 变量 - 应用程序将配置的代理注入所有代理进程

macOS“损坏”/网守

v0.2.19 的官方 GitHub 版本由开发者 ID 签名并 Apple 公证。打开 .dmg 并将 Grok 像往常一样拖到应用程序中。

如果 Gatekeeper 仍然阻塞（分叉/较旧的未签名版本，或剩余的隔离标志）：

xattr -cr /Applications/Grok.app
open /Applications/Grok.app

也有效：

  • Finder：右键单击 → 打开 → 确认
  • 系统设置 → 隐私和安全 → 仍然打开

只能从该仓库的官方 版本 下载。

Linux blank/black 窗口 (WebKit)

在某些 Wayland 桌面（特别是 Hyprland + AMD）上，官方 AppImage 可以打开一个保持全黑的窗口。主机进程仍在运行（媒体服务器、代理 ACP、身份验证），但捆绑的 WebKitGTK 从不绘制。日志通常包括：

Could not create default EGL display: EGL_BAD_PARAMETER

这是已知的 Tauri 2 + AppImage + WebKitGTK 类问题：AppImage 在 CI 容器 (Ubuntu 22.04) 中内置 WebKit，该容器可能会在较新的主机 Mesa/DRI 上失败堆栈。 .deb / .rpm 链接 系统 WebKit 和通常在同一台机器上没问题。请参阅问题 #539 和 Tauri Linux 图形注释。

按顺序尝试：

  1. 优先选择同一版本（系统 WebKit）中的 .deb 或 .rpm。在 Arch 上，使用 debtap 进行转换或提取 .deb 并运行二进制文件。
  2. 针对系统 WebKit 运行 AppImage（在 Arch + Hyprland + AMD 上确认）：
# one-time extract
./Grok_*.AppImage --appimage-extract
# or: bash scripts/run-linux-appimage-system-webkit.sh ./Grok_*.AppImage

export LD_LIBRARY_PATH=/usr/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
export WEBKIT_EXEC_PATH=/usr/lib/webkit2gtk-4.1
export WEBKIT_DISABLE_DMABUF_RENDERER=1
export WEBKIT_DISABLE_COMPOSITING_MODE=1
export GDK_BACKEND=x11
unset APPDIR APPIMAGE
./squashfs-root/usr/bin/grok-app

在 Debian/Ubuntu 多架构主机上，如果缺少上述路径，请使用 /usr/lib/x86_64-linux-gnu 和 /usr/lib/x86_64-linux-gnu/webkit2gtk-4.1。如果需要，安装系统 WebKit（Arch 上的 webkit2gtk-4.1；Debian/Ubuntu 上的 libwebkit2gtk-4.1-0）。

  1. 快速仅限 env 的尝试（有助于 NVIDIA/DMABUF 情况；对于上面的 EGL 中止来说，通常不够）：
WEBKIT_DISABLE_DMABUF_RENDERER=1 ./Grok_*.AppImage

Linux 沙箱/用户命名空间 (Ubuntu 24.04+)

在 Ubuntu 24.04+ （以及其他一些发行版）上，内核可能会设置：

kernel.apparmor_restrict_unprivileged_userns = 1

Grok 的默认代理沙箱 (--sandbox workspace) 使用 bubblewrap，它需要非特权用户命名空间。当内核阻止时，代理会立即退出，应用程序可能会显示 代理进程结束 / SANDBOX_BLOCKED（stderr 通常包括 bwrap: setting up uid map: Permission denied）。请参阅问题 #541。

修复（保留沙箱）：

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/99-userns.conf

不使用 sudo 的解决方法： 设置 → 运行时 → 沙箱 → 关闭（跳过 bwrap；失去 OS- 级别隔离）。

当 sysctl 受到限制且沙箱不是 off 时，Doctor 也会显示此问题。

配置路径

默认数据根（用 GROK_APP_HOME 覆盖）：

平台 典型路径
macOS ~/Library/Application Support/com.grokapp.grok-app/
窗户 %APPDATA%grokappgrok-app
回退 ~/.grok-app/ 
<app-data>/
  projects.json
  sessions_index.json
  settings.json
  secrets.json          # metadata (+ API-key fallback); keys prefer OS keychain
  automations.json
  projects/
  sessions/
  logs/
  agent-home/           # independent-mode GROK_HOME

API 密钥更喜欢 OS 秘密存储（macOS 钥匙串/Windows 凭据管理器/ Linux Secret Service）在 OS 存储时使用 secrets.json（模式 0600）回退 不可用。不要泄露秘密。

Grok Build 自己的配置仍然位于 ~/.grok 下（CLI 登录、auth.json，...）。
共享会话模式可以使用~/.grok； 独立模式使用agent-home/。

开发和建设

# Needs: Node 22+, pnpm 9, Rust stable, Xcode CLT (macOS)
pnpm install

pnpm dev                 # full app (real CLI by default)
pnpm dev:ui              # frontend only
GROK_APP_ACP=mock pnpm dev

pnpm typecheck && pnpm test
cd src-tauri && cargo test

pnpm build

交叉编译和发行说明：docs/BUILD.md。

发布（先写入匹配的CHANGELOG.md部分）：

./scripts/release-tag.sh 0.1.1
./scripts/release-tag.sh 0.1.1 --push

相关文章

精彩推荐