人工智能AI 应用AI Agent代码智能体开发工具CLIMCP Clients【免费下载链接】grok-buildSpaceXAIs coding agent harness and TUI. Fullscreen, mouse interactive, extensible.项目地址https://gitcode.com/gh_mirrors/gr/grok-build点击查看免费下载本篇指南以 grok-build 的官方用户手册 02-authentication.md 为骨架结合仓库中xai-grok-shell与xai-grok-auth的认证实现源码系统讲解 grok 的六种登录方式浏览器 OAuth、API Key、企业 OIDC、外部认证提供方、设备码以及凭据存储、自动刷新、热重载与认证优先级等运行机制。读完本文你将能够为本地开发、CI/CD 与无浏览器环境分别选择正确的认证方案并能在认证失败时借助日志与源码快速定位问题。认证方式总览grok 支持以下认证方法覆盖从个人电脑到企业内网、从交互式终端到无人值守 CI 的全场景认证方式适用场景入口浏览器登录默认本地交互使用首次启动自动触发grok、grok loginAPI KeyCI/CD、自动化脚本、无浏览器环境XAI_API_KEY环境变量OIDC企业 SSO通过自有 IdPOkta、Azure AD、Auth0登录config.toml/GROK_OIDC_*环境变量外部认证提供方沙箱 VM、CI Runner、隔离网络由外部二进制托管认证[auth] auth_provider_command设备码流程SSH 会话、Docker、远程 VM本地无浏览器grok login --device-auth从源码结构看这些方法统一由xai-grok-shellcrate 的 auth 模块 管理flow.rs负责交互式登录流程的路由config.rs定义各认证方法的配置结构manager.rs负责凭据的读取与持久化external_auth.rs专门执行外部认证提供方。浏览器登录默认首次启动时直接运行grokgrok 会自动打开浏览器跳转到 SpaceXAI 的 OAuth 授权页auth.x.ai完成认证。成功后凭据写入~/.grok/auth.json并在后续会话间复用访问令牌在后台自动刷新涉及 OIDC 时通过保存的refresh_token静默续期当令牌无法刷新时grok 会提示你重新登录服务端未提供过期时间的凭据回退为30 天的有效期源码 auth/model.rs 中通过TOKEN_TTL常量实现该回退逻辑。凭据存储与安全令牌保存在~/.grok/auth.jsonMCP OAuth 令牌则在~/.grok/mcp_credentials.jsonUnix 下以属主独占权限0600写入。注意任何对这两个路径拥有文件系统访问权限的人都能直接使用这些凭据因此请遵循优先启用全盘加密FileVault、BitLocker、LUKS 或同类方案不要把auth.json、mcp_credentials.json复制进共享目录、工单或聊天记录在多用户主机上让$HOME/$GROK_HOME保持仅自己账户可访问。另外从仓库中的锁测试flock_wait_tests.rs可以看出auth.json的并发写入由auth.json.lock文件锁保护避免多个进程如grok login与正在运行的 TUI同时写文件导致损坏。重新登录与登出切换账号或解决认证问题grok logingrok login会重新走一遍登录流程并替换缓存的会话。默认打开浏览器、通过 SpaceXAI OAuthauth.x.ai登录也可以传旗标选择其他流程旗标说明--oauth通过 SpaceXAI OAuth 登录auth.x.ai。这是默认行为旗标可省略。--device-auth别名--device-code使用设备码流程登录适用于无头或远程环境。登出使用grok logout该命令不接受任何旗标直接清除缓存的凭据。源码层面这两个旗标被映射为LoginTransportOverride枚举flow.rs--oauth强制走 loopback 回调流程--device-auth强制走 RFC 8628 设备流程两者同时设置时--oauth优先。API KeyCI/CD 或自动化对于 CI/CD、自动化或没有浏览器访问权限的环境可以在 console.x.ai 控制台创建 API key 后通过环境变量注入export XAI_API_KEYxai-... grok关键行为API key 只在没有活跃会话令牌时作为回退使用如果你已经交互式登录过存储的会话令牌优先于 API key想回退到 API key执行grok logout或删除~/.grok/auth.json。在源码中XAI_API_KEY属于AuthMode::ApiKey路径。仓库还提供了企业级管控开关设置GROK_DISABLE_API_KEY_AUTH后xai.api_key认证方法既不会被宣传也不会被接受config.rs防止 API key 绕过企业 IdP 登录——该环境变量锁定在运行期读取用户层config.toml无法将其关闭。此外[auth] preferred_method api_key可以把自动认证钉死在 API key 上此时所有自动 OIDC 路径devbox 铸造、浏览器登录、外部认证提供方均被 fail-closed 阻断config.rs。OIDC企业 SSOOIDC 让开发者通过你们自己的身份提供商IdP——例如 Okta、Azure AD、Auth0——完成认证而不是使用 grok.com 账号。1. 在 IdP 中注册一个公共客户端授权类型Authorization Code with PKCEProof Key for Code Exchange回调 URIhttp://127.0.0.1/callback——这是一个 loopback 地址。grok 在登录时绑定一个随机端口大多数 IdP 按照 RFC 8252 将 loopback 回调视为与端口无关不需要 client secretPKCE 取代了它。2. 配置 CLI通过配置文件推荐# ~/.grok/config.toml [grok_com_config.oidc] issuer https://acme.okta.com client_id 0oa1b2c3d4e5f6g7h8i9或通过环境变量export GROK_OIDC_ISSUERhttps://acme.okta.com export GROK_OIDC_CLIENT_ID0oa1b2c3d4e5f6g7h8i9还可以覆盖 API 端点指向你自己的代理export GROK_CLI_CHAT_PROXY_BASE_URLhttps://grok-proxy.acme.com/v13. 运行grokCLI 通过{issuer}/.well-known/openid-configuration自动发现端点打开 IdP 登录页并把令牌写入~/.grok/auth.json。令牌通过保存的refresh_token静默自动刷新。可选字段字段默认值说明scopes[openid, profile, email, offline_access, api:access]offline_access开启静默令牌刷新audience无某些 IdP如 Auth0要求设置源码印证OidcAuthConfig结构体config.rs正是[grok_com_config.oidc]的序列化映射默认 scopes 由default_oidc_scopes()函数定义config.rsGROK_OIDC_SCOPES逗号分隔与GROK_OIDC_AUDIENCE也可作为环境变量覆盖这两项。认证作用域 key 的格式为{issuer}::{client_id}用于在auth.json中区分不同登录来源config.rs。需要留意OIDC 登录始终走 loopback 流程——企业 IdP 通常不提供设备码端点因此--device-auth在企业 OIDC 配置下会自动回退到 loopbackflow.rs。外部认证提供方External Auth Provider当浏览器登录不可行时——例如沙箱化 VM、CI Runner、隔离网络——可以把认证委托给一个外部二进制或脚本。工作原理-------------- sh -c ------------------------ | Grok |--------------| your auth binary | | | | | | reads |-- stdout ----| prints token | | auth.json | | | | | (stderr) | prints status/URLs |-- surfaced to user -------------- ------------------------流程共五步grok 通过sh -c command运行你的命令你的二进制执行所需的任意认证流程SSO、设备码、证书交换stderr携带人类可读的输出如登录 URL 与状态消息。grok 读取 stderr 并展示给用户在 TUI 中stderr 里第一个https://URL 会被转换为可点击的登录链接stdout被 grok 捕获并保存为访问令牌退出码 0 成功非零退出码 grok 回退到交互式登录。stdout / stderr 契约流打印什么谁看到stdout只有令牌别无其他grok解析后存入 auth.jsonstderr登录 URL、状态消息、错误用户grok 读取 stderr并在 TUI 中把登录 URL 显示为可点击链接不要在 stdout 上打印除令牌以外的任何内容——不要打印进度消息不要打印调试输出。grok 读取 stdout、裁剪首尾空白后将其解析为令牌。stdout 令牌格式裸字符串——直接输出原始令牌eyJhbGciOiJSUzI1NiIs...JSON——可携带 refresh token、过期时间与 issuer{access_token: eyJhbGciOi..., refresh_token: ref-tok, expires_in: 3600, issuer: https://idp.example.com}如果你的令牌会过期、并希望 grok 在过期前自动重新运行你的二进制请使用 JSON 格式。JSON 字段如下字段是否必需含义access_token是grok 发送给 xAI API 的 Bearer 令牌refresh_token否仅存储备查。grok 通过重新运行你的二进制来刷新而不是使用 OAuth refresh grantexpires_in否令牌生命周期秒启用过期前的主动刷新issuer否标识令牌的签发方解析实现细节token_output.rs只要输出以{开头就会被当作 JSON 令牌负载并要求能解析出非空access_token否则视为裸字符串令牌JWT 与不透明令牌不会以{开头因此{error:expired}这类错误对象永远不可能被误当成 Bearer。非零退出码、非 UTF-8 输出、空 stdout、空access_token或非法 JSON 负载一律判为失败——畸形输出 fail closed绝不会被送上线路。配置通过配置文件# ~/.grok/config.toml [auth] auth_provider_command /usr/local/bin/my-auth-provider auth_provider_label Acme Corp # 可选 -- 自定义 TUI 登录按钮文案 auth_token_ttl 3600 # 可选 -- 令牌生命周期秒或通过环境变量export GROK_AUTH_PROVIDER_COMMAND/usr/local/bin/my-auth-provider export GROK_AUTH_PROVIDER_LABELAcme Corp export GROK_AUTH_TOKEN_TTL3600源码确认GrokComConfig中auth_provider_command、auth_provider_label、auth_token_ttl三个字段分别由同名环境变量直接填充config.rs。其中auth_token_ttl用于给输出裸字符串令牌没有expires_in的外部提供方合成expires_at从而让主动刷新机制生效。令牌刷新GROK_AUTH_EXPIRED双契约grok 在两种不同契约下运行你的二进制GROK_AUTH_EXPIRED环境变量就是区分信号。每次运行都会完全替换已存储的凭据因此每次调用包括刷新都要输出相同的 JSON 字段如issuer。GROK_AUTH_EXPIRED1—— 无头刷新headless refresh。grok 在为自己已持有的凭据重新铸造令牌即将过期的轮换或服务端已拒绝的令牌。此时无人观看。stdin 已关闭你的 stderr 会被吞掉二进制只有几秒钟时间超时即被杀。请静默铸造令牌或直接非零退出——绝不阻塞。变量未设置 —— 登录sign-in。grok login、登录界面或无头刷新铸造失败后 grok 发起的升级登录。此时有用户在等待你的 stderr 会送达用户并且你有300 秒——足够完成一次浏览器往返或一次设备码输入。一个同时处理两种契约的参考脚本#!/bin/sh if [ $GROK_AUTH_EXPIRED 1 ]; then # 无头模式只做静默刷新。当你的 SSO 会话已过期且只有用户能续期时 # 快速拒绝是正确的答案。 echo Refreshing token... 2 TOKEN$(my-company-auth --refresh --silent) || exit 1 else echo Authenticating via Acme Corp SSO... 2 TOKEN$(my-company-auth --login --interactive) fi if [ -z $TOKEN ]; then echo Authentication failed 2 exit 1 fi echo {\access_token\: \$TOKEN\, \expires_in\: 3600}当无头刷新拿不到令牌时grok 会停止把已存储凭据视为可用转而启动登录流程——与你从未登录过的机器上触发的是同一个流程此时你的二进制 stderr 会显示出来设备码 URL 或浏览器提示能到达你。在GROK_AUTH_EXPIRED1时快速退出正是让这次交接变快的关键阻塞的二进制只会让你每次启动都白白等完刷新超时。会话中途则该轮请求失败并出现重新认证提示/login会以交互方式重新运行你的二进制。源码级时间约束无头刷新的硬性超时是 7 秒EXTERNAL_AUTH_REFRESH_TIMEOUT见 external_auth.rs并通过进程组杀手在超时时将二进制及其子进程一并终止超时消息会记录为 timed out (a timeout usually means it needs interactive sign-in)external_auth.rs。交互式登录的上限则是 300 秒。一个边界情形仅 leader 模式--leader或[cli] use_leader true默认关闭。在没有任何凭据的情况下leader 会在启动后的后台额外尝试一次而这次运行的GROK_AUTH_EXPIRED未设置与登录无异。能够自主铸造令牌的二进制服务账号、keytab、挂载令牌在此次尝试中成功会话自我修复必须提示用户的二进制则最多等待 300 秒的登录上限——没有人在等它登录界面早已弹出而且这次运行的 stderr 会写入~/.grok/leader.log而不是直接给你看。环境变量汇总变量说明GROK_AUTH_PROVIDER_COMMAND你的认证二进制路径GROK_AUTH_PROVIDER_LABELTUI 登录界面上的显示名如 Acme CorpGROK_AUTH_TOKEN_TTL令牌生命周期秒用于没有expires_in的裸字符串令牌GROK_AUTH_EXPIRED无头刷新时设为1不要提示也不要交回缓存的令牌。登录时未设置有用户在场GROK_AUTH_EARLY_INVALIDATION_SECS过期前主动刷新的提前量默认 300 秒仓库中还提供了完整的端到端测试可以对照学习外部认证提供方的符合性测试在 external_auth_conforming_provider.rs凭据过期场景在 external_auth_expired_credential.rsauth_provider_command的 E2E 验证在 test_auth_provider_command_e2e.rs。设备码流程Device Code Flow适用于本地没有可用浏览器的无头环境SSH 会话、Docker 容器、远程 VMgrok login --device-auth # 或: grok login --device-code该命令会在终端打印一个 URL 和验证码。在任意设备上打开 URL、输入验证码即可完成认证grok 会轮询直到登录被确认。设备码流程同样可以通过外部认证提供方自行实现以获得完全控制。流转决策的优先级flow.rs——设备流程是否启用按以下层级解析CLI 旗标--oauth/--device-authGROK_LOGIN_DEVICE_FLOW环境变量 [auth] login_device_flow配置 远端特性开关grok_build_login_device_flow 默认的 loopback 流程。远端特性开关的拉取还有 2 秒超时兜底慢速网络不会卡死登录flow.rs。自动凭据刷新grok 会自动刷新过期的凭据触发条件有三类过期前如果认证提供方返回了expires_inJSON 输出或你设置了auth_token_ttlgrok 会在过期前约 5 分钟重新运行认证二进制认证错误服务端返回 401 Unauthorized 时grok 刷新凭据并重试该请求OIDC若存在refresh_tokengrok 通过你的 IdP 静默刷新不再重新打开浏览器。刷新提前量可以调节# 过期前 5 分钟刷新默认 export GROK_AUTH_EARLY_INVALIDATION_SECS300 # 关闭主动刷新缓冲仅在过期时或收到 401 时刷新设为 0 export GROK_AUTH_EARLY_INVALIDATION_SECS0源码印证默认提前量常量DEFAULT_EARLY_INVALIDATION_SECS: u64 3005 分钟定义在 auth/model.rs实际判断Utc::now() (expires_at - buffer)在is_expired_with_bufferauth/model.rs对没有expires_at的凭据则用创建时间加上 TTL 推算。无头刷新与 401 触发刷新的路径在 external_auth.rs 中命令以GROK_AUTH_EXPIRED1启动7 秒超时成功则日志记录 auth: external auth provider returned fresh token且新凭据会保留旧凭据中的用户资料字段如 ZDR 标志、组织 ID见refresh_with_command及其测试external_auth.rs。热重载Hot Reloadgrok 会自动感知~/.grok/auth.json的变化。如果你在外部更新了凭据例如用脚本写入新令牌无需重启grok 会在下一次 API 调用时直接使用新凭据。从架构上看AuthCredentialProvider::snapshot()在每次取凭据前都会做一次廉价的磁盘重读见 auth_provider.rs 与 xai-grok-shell/src/auth/credential_provider.rs因此来自兄弟进程grok-desktop、grok login的更新能即时可见。认证优先级Auth Precedencegrok 对每个请求按以下顺序解析凭据从高到低每个模型的api_key或env_key—— 在config.toml的[model.name]下设置。只要存在即生效即 BYOK 模式参见 11-custom-models.md活跃的会话令牌—— 通过浏览器、OIDC/OAuth2 或外部提供方登录获得存储于~/.grok/auth.jsonXAI_API_KEY—— 没有活跃会话令牌时的回退。当配置了多个登录流程时grok 按以下顺序从高到低用第一个可用来源填充会话令牌外部认证提供方auth_provider_command企业 OIDC—— 通过config.toml的[grok_com_config.oidc]或GROK_OIDC_ISSUER/GROK_OIDC_CLIENT_ID环境变量配置SpaceXAI OAuth2 浏览器登录—— 默认方式。会话期间中途的所有刷新都由当时活跃的方式负责处理。相关设置需要注意编码数据共享Settings 中的 Coding data, retention, and training/privacy命令可打开不会改变以下这些配置旋钮设置如何设置[features] telemetryconfig.toml或GROK_TELEMETRY_ENABLED[telemetry] trace_uploadconfig.toml或GROK_TELEMETRY_TRACE_UPLOAD外部 OpenTelemetryGROK_EXTERNAL_OTEL/[telemetry] otel_*。参见 监控用量在企业团队账号下只有团队管理员能修改编码数据共享团队管理员还可以为团队启用或禁用 Zero Data RetentionZDR。ZDR 开启后编码数据共享完全不可修改——设置项的值会显示为ZDR。更多内容参见 监控用量 与 配置。故障排查调试日志设置RUST_LOG可以控制文件日志与无头模式 stderr 输出的详细程度TUI 的屏幕内 tracing 面板使用固定过滤条件忽略RUST_LOG。TUI 中文件日志默认为DEBUG无头模式-p下RUST_LOG默认为off只输出答案——设置RUST_LOGerror或更宽即可在 stderr 看到日志。TUI 中可用GROK_LOG_FILE指定绝对路径写日志GROK_LOG_FILE/tmp/grok.log RUST_LOGdebug grok tail -f /tmp/grok.logGROK_LOG_FILE被当作字面文件路径处理。相对值如1会在当前目录写一个名为1的文件。无头模式下日志走 stderr可重定向到文件RUST_LOGdebug grok -p hello 2 /tmp/grok.log常见日志消息这些日志文本与源码 external_auth.rs 中的tracing调用一一对应可作为排查线索日志消息含义auth: running external auth provider (headless refresh)/(interactive login)grok 正在运行你的二进制以及是哪种契约auth: external auth provider returned fresh tokengrok 已解析并存储令牌auth: external auth provider failed二进制非零退出或 stdout 为空auth: external auth provider timed out (likely needs interactive auth), killing二进制在超时前未退出已被终止auth: failed to start external auth provider命令无法生成二进制不存在常见修复Authentication failed—— 执行grok logout清除缓存的凭据再执行grok login重新登录令牌过期太快—— 设置auth_token_ttl或在认证提供方的 JSON 输出中返回expires_inOIDC 重定向失败—— 确认你的 IdP 允许 loopback 回调 URIhttp://127.0.0.1/callback找不到外部认证提供方—— 检查auth_provider_command的路径是否正确、二进制是否可执行。延伸阅读完整配置参考26-config-reference.md配置分层与环境变量详解05-configuration.md每模型 API key 与 BYOK11-custom-models.md认证实现源码xai-grok-shell/src/auth/config.rs、flow.rs、external_auth.rs、token_output.rs、model.rs认证凭据提供者抽象xai-grok-auth/src/auth_provider.rs端到端测试external_auth_conforming_provider.rs、external_auth_expired_credential.rs、test_auth_provider_command_e2e.rs赞分享人工智能AI 应用AI Agent代码智能体开发工具CLIMCP Clients【免费下载链接】grok-buildSpaceXAIs coding agent harness and TUI. Fullscreen, mouse interactive, extensible.项目地址https://gitcode.com/gh_mirrors/gr/grok-build点击查看免费下载相关推荐WeKan 登录与认证体系深度解析从客户端登录表单到 OIDC、LDAP、SAML 企业级认证WeKan 登录与认证体系深度解析从客户端登录表单到 OIDC、LDAP、SAML 企业级认证 导读 本文以 READMELoginSignUp.md htt后端前端协同办公Remix 认证原语实战使用 remix/auth 组合凭据认证与 OAuth/OIDC 外部登录Remix 认证原语实战使用 remix/auth 组合凭据认证与 OAuth/OIDC 外部登录 导读 remix/auth 是 Remix 框架中一套可组后端前端Web框架grok-build 0.2.34grok login 默认切换 Device Code 登录流并修复认证刷新卡死grok build 0.2.34 grok login 默认切换 Device Code 登录流并修复认证刷新卡死 版本要点速览 grok build人工智能AI 应用AI Agent代码智能体开发工具CLIMCP Clients上一篇MobuLiveLink 项目常见问题解决方案下一篇Static Web Server 完全指南如何快速部署高性能静态文件服务器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考