# Grok OAUTH Router

> 统一使用 Grok 完成聊天、推理、X 搜索、图片生成、视频生成、文本转语音、语音转文字和代理接入的能力路由技能。只要用户明确说“用 Grok”“走 Grok OAuth”“用 xAI/Grok 做某件事”，或者上下文明显要求把任务交给 Grok 处理时，就应该触发本技能。遇到未登录、令牌失效、需要先完成 OAuth 再恢复原任务、或需要区分 entitlement 拒绝与重新登录时，也必须使用本技能。

- Skill: `moore-developers/grok-oauth-router` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add moore-developers/grok-oauth-router`
- Raw SKILL.md: https://api.skillmd.com/api/skills/moore-developers/grok-oauth-router/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: moore-developers (https://skillmd.com/u/moore-developers)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/moore-developers/grok-oauth-router

---


# Grok OAuth Router

## 任务定义

这个技能的目标不是单纯解释 Grok OAuth，也不是只把模型切换到 Grok。

你的职责是把用户的“用 Grok 做 X”转换成一个可执行的完整流程：

1. 判断用户要用的是哪一种 Grok 能力。
2. 判断当前是否已经具备可复用的 Grok OAuth。
3. 如果还没有，则先走 OAuth。
4. 保存凭据以供后续复用。
5. 恢复并继续执行用户原始任务。

默认使用用户自己的 OAuth。

默认坚持 OAuth-first。不要静默退回 API key 模式。只有在用户明确允许时，
才把 API key 作为异常回退路径。

## 何时触发

当出现下面这些情况时，应当触发本技能：

- 用户明确说“用 Grok 做……”
- 用户明确说“走 Grok OAuth”
- 用户明确说“用 xAI / Grok 来处理这个任务”
- 用户希望统一通过 Grok 完成聊天、搜索、图片、视频、语音或转写能力
- 用户当前任务已经表明必须优先使用 Grok，而不是其他 provider

高频示例：

- 用 Grok 总结这个仓库
- 用 Grok 去 X 上搜大家怎么评价这个发布
- 用 Grok 生成一张图
- 用 Grok 生成一个短视频
- 用 Grok 把这段话读出来
- 用 Grok 把这段录音转成文字
- 用 Grok 的代理接口给别的工具使用

## 能力分类

先把用户任务归类到以下内部模式之一：

- `chat`
- `x_search`
- `image_gen`
- `video_gen`
- `tts`
- `stt`
- `proxy`

归类原则：

- 没有明确媒体或工具诉求时，默认按 `chat` 处理
- 提到 X / Twitter / 推文 / 线程 / 社交反应时，优先考虑 `x_search`
- 提到生成图片、海报、概念图、插画、渲染时，优先考虑 `image_gen`
- 提到生成视频、动画、图生视频时，优先考虑 `video_gen`
- 提到朗读、配音、语音播报时，优先考虑 `tts`
- 提到转录、转写、语音识别、字幕时，优先考虑 `stt`
- 提到 OpenAI-compatible、代理端点、给别的工具接入时，优先考虑 `proxy`

## 执行流程

始终按下面的顺序处理：

### 1. 先识别原始任务

不要一看到 Grok 就只讨论认证。先提炼出用户真正想完成的任务。

你需要在内部保留一个简短的“原始任务摘要”，用于认证完成后的自动续跑。

### 2. 检查 OAuth 状态

优先复用已有的 Grok OAuth 状态。检查重点包括：

- 是否已有已保存的 xAI OAuth 状态
- access token 是否存在
- token 是否仍可用
- 是否已经进入需要重新登录的状态
- 是否属于 entitlement / tier 被拒绝，而不是普通登录失效

如果 OAuth 已可用，就直接继续执行原始任务。

### 3. 没有 OAuth 时先认证

如果没有可用 OAuth，就先完成认证，再继续任务。

认证模式优先级：

- 本地桌面环境：使用浏览器 loopback 回调
- SSH / 远程环境：使用远程 listener + 本地端口转发
- 浏览器型远端环境：使用手动粘贴 callback 的方式

认证完成后要做两件事：

- 保存凭据，供未来 Grok 任务复用
- 自动恢复原始任务，而不是停在“登录成功”

### 4. 把任务路由到正确能力面

认证通过后，按能力类型继续：

- `chat`
  用 Grok 作为主模型完成聊天、推理、分析、总结、工具调用等任务

- `x_search`
  优先使用 Grok 的 X 搜索能力，而不是泛化成普通网页搜索

- `image_gen`
  路由到 Grok 图片生成能力

- `video_gen`
  路由到 Grok 视频生成能力

- `tts`
  路由到 Grok 文本转语音能力

- `stt`
  路由到 Grok 语音转文字能力

- `proxy`
  路由到 Grok 兼容代理能力

### 5. 自动续跑原任务

认证只是前置步骤，不是结果。

认证成功后，直接继续执行原始任务，不要要求用户重复说一遍“刚才那个任务”。

## 错误处理规则

必须区分两类问题：

### 需要重新登录

这类问题通常意味着：

- 本地没有可用 OAuth
- refresh token 失效
- token 过期且无法正常刷新
- 需要重新完成浏览器授权

遇到这种情况时，应该把重点放在“先完成认证，再自动恢复原任务”。

### entitlement / tier 被拒绝

这类问题不是简单重新登录就能解决的。

当判断为 entitlement、tier、allowlist 或 API 权限被拒绝时：

- 不要把它误报成“重新登录即可解决”
- 明确告诉用户这是账号权限层面的拒绝
- 默认不要静默切到 API key
- 只有在用户明确允许时，才讨论 API key 回退方案

### 能力面与模型不匹配

如果某个 Grok 模型不支持 `x_search` 或某个工具能力：

- 明确指出问题在“模型能力不匹配”
- 优先切换到支持该能力的 Grok 模型
- 不要把这类问题误判为 OAuth 失败

## 用户交互规则

与用户沟通时遵守下面的规则：

- 把用户目标放在前面，不要把认证当主角
- 认证需要用户配合时，用简短说明解释下一步
- 认证完成后，主动继续执行原任务
- 不要默认让用户在 OAuth 和 API key 之间做开放式选择
- 只有在真正存在风险分叉时，才向用户确认

如果认证会打断当前执行，应当明确保留原始任务语义，例如：

- “我先帮你完成 Grok OAuth，完成后继续用 Grok 搜 X 上的讨论。”
- “我先把 Grok 登录状态准备好，然后继续用 Grok 生成图片。”

## 参考文档使用方式

优先按需读取以下文档：

- `./grok-skill-routing-plan.md`
  用于理解整体设计目标、路由边界和运行时状态机

- `./capability-matrix.md`
  用于确认当前 Grok 能力面和路由范围

- `./oauth-flow.md`
  用于理解 OAuth 的用户路径、本地 / SSH / manual-paste 分支，以及恢复原任务的要求

- `./constraints-and-risks.md`
  用于判断哪些情况属于能力限制、上游变化或路由风险

- `./hermes-grok-oauth-parameter-observations.md`
  只在需要研究兼容性细节时读取。这里记录的是 Hermes 当前可观察到的参数、
  固定值和行为特征，用于兼容性判断，而不是稳定不变的官方契约。

## 关于 Hermes 参数与值

需要理解下面这个边界：

- 这个技能的目标是让用户用自己的 OAuth 使用 Grok 的全部能力
- Hermes 当前使用的参数、值和请求形状，是兼容性观察输入
- 不要把这些参数和值包装成对用户的表层概念
- 不要把“复制 Hermes”本身当成用户目标

在真正需要分析兼容性问题时，再去查阅参数观察文档。

## 输出要求

当任务完成时：

- 先给出 Grok 任务结果
- 再简短说明是否进行了 OAuth 复用或新认证

当任务被认证阻塞时：

- 明确说明正在为哪个原始 Grok 任务做前置认证
- 保留原始任务摘要
- 认证完成后自动继续

当任务被 entitlement 阻塞时：

- 明确这是权限 / tier 问题
- 不要误导用户反复重新登录

## 示例

### 示例 1：聊天任务

用户：用 Grok 帮我总结这个仓库的核心架构。

你的处理：

1. 识别为 `chat`
2. 检查是否已有 Grok OAuth
3. 如果没有，先完成认证
4. 认证成功后，继续总结仓库架构

### 示例 2：X 搜索任务

用户：用 Grok 去 X 上搜一下大家对 Grok 新功能的反应。

你的处理：

1. 识别为 `x_search`
2. 检查 OAuth
3. 必要时先完成认证
4. 再继续用 Grok 的 X 搜索能力完成任务

### 示例 3：图像任务

用户：用 Grok 生成一张复古未来主义风格的产品海报。

你的处理：

1. 识别为 `image_gen`
2. 检查 OAuth
3. 必要时先认证
4. 再继续生成图片，而不是停在登录说明