首次运行与认证

文档摘要

首次运行与认证本节摘要:装好二进制只是第一步,要真正用起来,还得完成首次运行与认证。Grok Build 在第一次启动时会打开浏览器引导你登录,登录成功后凭据被缓存到本地,之后无需重复登录。与此同时,一个名为的目录会被建立起来,成为 Grok Build 在你机器上的「家」——配置、认证、会话、记忆、日志统统存放于此。本节会带你走完这最后一公里:认证流程的原理、凭据如何存储、以及目录的完整结构。读完后,你就从「装好了」真正进入「能用」的境界。一、首次启动会发生什么当你第一次执行 (或源码构建的 )时,大致经历这样的流程: 整个过程对用户来说,就是「弹出一个浏览器 → 登录 → 回到终端继续」。但这背后是一套标准的 OAuth2 流程,值得理解其原理。

首次运行与认证

本节摘要:装好二进制只是第一步,要真正用起来,还得完成首次运行与认证。Grok Build 在第一次启动时会打开浏览器引导你登录,登录成功后凭据被缓存到本地,之后无需重复登录。与此同时,一个名为 ~/.grok/ 的目录会被建立起来,成为 Grok Build 在你机器上的「家」——配置、认证、会话、记忆、日志统统存放于此。本节会带你走完这最后一公里:认证流程的原理、凭据如何存储、以及 ~/.grok/ 目录的完整结构。读完后,你就从「装好了」真正进入「能用」的境界。

一、首次启动会发生什么

当你第一次执行 grok(或源码构建的 xai-grok-pager)时,大致经历这样的流程:


1. 程序启动,初始化日志、遥测、崩溃处理器
2. 解析命令行参数与当前工作目录
3. 检查认证状态:
   - 是否有 XAI_API_KEY 环境变量?
   - ~/.grok/auth.json 是否存在且未过期?
4. 若无有效凭据:
   - 默认走 OAuth2 浏览器登录流程
   - 启动一个本地回调服务器(随机端口)
   - 打开默认浏览器到登录页
5. 用户在浏览器完成登录
6. 浏览器重定向回本地回调,带回授权码
7. 程序用授权码换取 access_token 与 refresh_token
8. 凭据写入 ~/.grok/auth.json
9. 进入正常的 TUI 或执行用户命令

整个过程对用户来说,就是「弹出一个浏览器 → 登录 → 回到终端继续」。但这背后是一套标准的 OAuth2 流程,值得理解其原理。

二、OAuth2 浏览器登录的原理

Grok Build 默认使用 OAuth2 进行认证,认证服务器是 XAI 的 auth 服务。它用的具体流程叫「Authorization Code with PKCE」(带 PKCE 的授权码流程),这是当前最安全的 OAuth2 客户端流程。

为什么用 PKCE

PKCE(Proof Key for Code Exchange)是为了保护「无法安全保存密钥的客户端」(如桌面应用、移动应用、SPA)而设计的。传统的 OAuth2 流程里,客户端有一个 client_secret,用它换取 token。但桌面应用无法安全保存这个 secret——任何人都能从二进制里提取出来。PKCE 用一个动态生成的挑战-应答对替代了 client_secret,既安全又不需要预置密钥。

流程详解


[1] Grok Build 启动登录
    生成 code_verifier(随机串)
    计算 code_challenge = SHA256(code_verifier)

[2] 启动本地回调服务器
    监听 http://127.0.0.1:<随机端口>/callback

[3] 打开浏览器到授权 URL
    https://auth.x.ai/...?
        client_id=...&
        redirect_uri=http://127.0.0.1:<端口>/callback&
        code_challenge=...&
        code_challenge_method=S256&
        ...

[4] 用户在浏览器登录并授权
    (这一步在 XAI 的服务器完成,Grok Build 看不到密码)

[5] 浏览器重定向回本地回调
    http://127.0.0.1:<端口>/callback?code=<授权码>

[6] Grok Build 收到授权码,用它与 code_verifier 换 token
    POST https://auth.x.ai/token
      code=<授权码>
      code_verifier=<原 verifier>
    → 返回 access_token + refresh_token

[7] 凭据写入 ~/.grok/auth.json

关键点:密码从不经过 Grok Build。用户在浏览器里输入密码,是与 XAI 服务器直接交互,Grok Build 只拿到一个授权码,用授权码换 token。这是 OAuth2 安全性的核心。

关键概念:OAuth2 + PKCE 让 Grok Build 既能代表你访问 XAI 服务,又永远拿不到你的密码。授权码只能用一次,且必须配合 code_verifier 才能换 token,即便被截获也无法重放。

三、凭据的存储与刷新

登录成功后,凭据存到 ~/.grok/auth.json。这个文件通常包含:

access_token:访问令牌,有效期较短(如 1 小时),用于调用 API
refresh_token:刷新令牌,有效期较长,用于在 access_token 过期后换取新的
过期时间:令牌何时过期
其他元数据:如签发者、scope 等

自动刷新

access_token 过期后,Grok Build 不会让你重新登录,而是用 refresh_token 在后台静默换取新的 access_token。这个过程对用户透明。只有当 refresh_token 也失效(如长期未用、被吊销、或 XAI 服务端策略调整)时,才会提示重新登录。

安全注意

auth.json 里存的是有效的访问凭据,任何拿到它的人都能以你的身份调用 API。因此:

不要把 ~/.grok/auth.json 提交到版本控制
不要随意分享这个文件
在共享机器上注意文件权限(限制为仅当前用户可读)
怀疑泄露时,用 grok logout 清除并重新登录

四、其他认证方式

OAuth2 浏览器登录是默认,但不是唯一选择。Grok Build 支持多种认证方式以适应不同场景:

API Key(环境变量)

设置 XAI_API_KEY 环境变量,程序会优先使用它,跳过 OAuth2 流程。这适合:

CI/CD 流水线(无浏览器)
脚本自动化
容器化部署

API Key 从 XAI 的控制台获取。注意:若有缓存的 OAuth2 凭据,要回退到 API Key 需先 grok logout 清除缓存。

设备码流程(无浏览器)

在无浏览器的远程环境(SSH、容器),可以用设备码流程:


grok login --device-auth

程序会显示一个 URL 与一个验证码,你在另一台有浏览器的设备上访问该 URL,输入验证码完成登录。这避免了在无 GUI 的服务器上打开浏览器的麻烦。

OIDC / 企业 SSO

企业用户可配置 OIDC(OpenID Connect)对接公司 SSO(如 Okta、Auth0)。这也是用 Authorization Code with PKCE 流程,只是认证服务器换成企业 IdP。配置通过 TOML 或环境变量指定 issuer 与 client_id,程序会自动发现端点。

外部认证 Provider

最灵活的方式——配置一个外部命令作为认证 provider,Grok Build 通过执行该命令获取 token。这适合企业有自定义认证协议、或想集成公司内部凭证系统的场景。provider 命令的 stdout 输出 token,stderr 输出登录 URL 供用户点击。

第 8 章讲 Headless 与 CI/CD 时,会再次涉及这些认证方式的选择。

五、`~/.grok/` 目录全貌

认证完成后,~/.grok/ 目录会逐步建立起来。这是 Grok Build 在你机器上的「家」,几乎所有本地状态都在这里。完整结构大致如下:


~/.grok/
├── config.toml              # 用户配置(主配置文件)
├── pager.toml               # TUI 表现层配置(主题等)
├── managed_config.toml      # 受管配置(企业/系统级下发)
├── requirements.toml        # 硬性要求(策略强制)
├── auth.json                # 认证凭据(OAuth2/API Key)
├── version.json             # 版本检查缓存
├── campaigns_state.json     # 推广活动状态(已忽略哪些等)
│
├── sessions/                # 会话存储(JSONL 格式,按工作目录分)
│   └── <编码后的工作目录>/
│       └── <session_id>/
│           ├── updates.jsonl        # 核心事件流
│           ├── chat_history.jsonl   # 简化历史(回放用)
│           ├── summary.json         # 会话摘要
│           └── ...
│
├── memory/                  # 跨会话记忆
│   ├── MEMORY.md            # 全局记忆
│   └── <工作区哈希>/        # 每个工作区一份
│       ├── MEMORY.md        # 工作区级记忆
│       ├── index.sqlite     # 混合检索索引(FTS5 + 向量)
│       └── sessions/        # 每会话的反思日志
│
├── skills/                  # 用户级 Skills
├── agents/                  # 用户级 Agent 定义
├── personas/                # 用户级 Persona 定义
├── plugins/                 # 用户级插件
├── hooks/                   # 用户级 Hooks(*.json)
│
├── logs/                    # 日志
│   ├── unified.jsonl        # 统一日志
│   └── mcp/                 # MCP 相关日志
├── crash/                   # 崩溃报告
├── trace-exports/           # 会话 trace 导出
│
├── worktrees/               # git worktree 元数据
└── bin/                     # 程序自身(grok 可执行文件)

几个关键观察:

第一,会话按工作目录组织。sessions/ 下不是平铺的所有会话,而是按「会话所在的工作目录」分组。这样不同项目的会话互不干扰。工作目录名经过编码(短的直接 URL 编码,长的用哈希)以兼容文件系统路径长度限制。

第二,memory 有混合检索索引。memory/ 不只是 Markdown,还有 SQLite 索引(FTS5 全文 + 向量 KNN),支撑跨会话记忆的混合搜索。这是唯一使用 SQLite 的地方——会话本身用 JSONL。

第三,扩展按目录组织。skills、agents、personas、plugins、hooks 都有各自的目录,这是 Grok Build 扩展生态的落点,第 6 章会详谈。

第四,配置有多层。config.toml(用户)、pager.toml(表现层)、managed_config.toml(受管)、requirements.toml(硬性要求)各司其职,优先级有明确规则,第 7 章会详谈。

GROK_HOME 环境变量

默认 ~/.grok/ 可通过 GROK_HOME 环境变量覆盖。这在以下场景有用:

多版本共存(不同 GROK_HOME 隔离不同版本的状态)
只读环境(CI 里把 GROK_HOME 指向临时目录,避免污染)
测试与实验(用临时 GROK_HOME 跑实验,完成后丢弃)

六、首次对话

认证完成、目录建立好后,你就可以开始第一次对话了。最简单的验证方式:


grok                    # 进入交互 TUI
                        # 在输入框输入:"你好,介绍一下你能做什么"
                        # 回车

如果一切正常,你应该看到 Agent 流式地回复,介绍它的能力。这标志着环境搭建全部成功——从工具链、protoc、安装、认证,到 ~/.grok/ 就位,Grok Build 已经是一个能用的工具了。

后续章节会深入这个工具的内部,但在那之前,你可以多用它熟悉基本交互。建议试试:

让它读一个你的项目,问几个关于代码的问题
让它跑一个简单的 shell 命令
试试 / 开头的斜杠命令(如 /help、/sessions)
观察权限询问的弹窗(当它想编辑文件时)

这些亲身体验,会让你在阅读后续章节的原理讲解时更有共鸣。

本节要点回顾

首次启动触发认证:无凭据时走 OAuth2 浏览器登录,凭据缓存后无需重复登录。
OAuth2 + PKCE 是默认流程:密码不经 Grok Build,授权码只能用一次且需 code_verifier,安全可靠。
凭据存 ~/.grok/auth.json:含 access/refresh token,后台自动刷新;注意文件安全,勿提交勿分享。
多种认证方式适应场景:API Key(CI)、设备码(无浏览器)、OIDC(SSO)、外部 provider(企业自定义)。
~/.grok/ 是 Grok Build 的家:会话(JSONL)、记忆(MD+SQLite)、扩展(skills/agents/...)、配置(多层 toml)、日志、崩溃报告。
会话按工作目录组织:不同项目互不干扰;memory 有混合检索索引;扩展按目录组织;配置分层。
GROK_HOME 可覆盖默认目录:用于多版本隔离、只读 CI、临时实验。
首次对话验证环境:能正常流式回复即标志搭建成功。

下一节,我们讲清构建 profiles 的取舍——release、release-dist、x-prod 这些名字背后是什么,以及为何「永远用 -p <具体 crate>」是开发铁律。

首次运行与认证

文档摘要