Grok quota

Skill uvwt/agentdock/skill-sources/grok-quota

Secure MCP runtime for AI agents to operate local machines, servers, and containers with multi-device orchestration.

Install

npx -y skills add uvwt/agentdock --skill grok-quota

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

Query detailed Grok weekly usage, GrokChat/GrokBuild breakdown, plan, monthly credits, and pay-as-you-go state from local xAI OAuth credentials.

SKILL.md

4.4 KB, as published. Nobody here has run it

Grok Quota

查询 Grok Build / GrokChat 的详细额度、套餐、周周期和月度积分。实现跟随 CPA 管理面板当前使用的 xAI Billing 协议。

动作

status：只读扫描本机 xAI OAuth 凭据，返回脱敏账号引用、token/refresh token 是否存在及过期状态；不发起额度请求。
query：优先调用两条只读 Billing 接口并合并结果；正常情况下不发起模型请求，也不消耗模型 token。只有 Billing 接口不可用时，才回退到最小 Responses 探测。

额度语义

CPA 新版管理面板会并行读取：

GET https://cli-chat-proxy.grok.com/v1/billing?format=credits
- 周期类型、周限额已用比例、周期开始/结束时间。
- productUsage 中的 GrokChat、GrokBuild 等产品已用比例。
GET https://cli-chat-proxy.grok.com/v1/billing
- 月度积分上限、已用积分、账期开始/结束时间。
- 按量付费上限和已用金额。

Skill 合并两条响应并返回：

套餐：当前已知 US$150 对应 SuperGrok，US$1500 对应 SuperGrok Heavy。
周限额：已用百分比、剩余百分比和重置时间。
产品拆分：GrokChat、GrokBuild 等各自已用/剩余百分比。
月度积分：已用、上限、剩余的美分和美元值，以及账期重置时间。
按量付费：是否启用、上限、已用和剩余金额。

当两条 Billing 接口均无法提供有效数据时，query 才向 /v1/responses 发起一个最小请求。回退探测只用于判断可用性或解析 429 中的 subscription:free-usage-exhausted，可能消耗少量 token；此时会明确返回 exact_details_available=false。

凭据来源

Skill 不接受 access token、refresh token 或 Cookie 作为输入。它只从外部 JSON auth 文件读取 xAI OAuth 凭据。

支持以下凭据来源：

官方 Grok Build CLI：$GROK_HOME/auth.json 或当前系统用户的 ~/.grok/auth.json。
输入 auth_file：一个绝对 JSON 文件路径。
输入 auth_dir：一个绝对目录路径。
环境变量 GROK_QUOTA_AUTH_FILE。
环境变量 GROK_QUOTA_AUTH_DIR 或 CLIPROXY_AUTH_DIR。
未配置显式来源时，扫描 ~/.cli-proxy-api/ 与 ~/.config/cli-proxy-api/。

即使已经配置 CPA auth 目录，Skill 仍会同时检查官方 Grok Build CLI 的 auth.json。多个账号时，先运行 status 获取脱敏 account_ref，再把该值传给 query。OAuth access token 过期时，Skill 可使用 auth 文件中的 refresh token 和对应 OIDC client ID 在内存中刷新一次，但不会改写原文件。

推荐通过 Skill 独立环境配置 CPA auth 目录：

GROK_QUOTA_AUTH_DIR=/path/to/cli-proxy-api/auths

输入示例

状态检查：

{
  "skill_action": "status"
}

查询唯一账号：

{
  "skill_action": "query"
}

指定账号与回退探测模型：

{
  "skill_action": "query",
  "account_ref": "脱敏账号引用",
  "model": "grok-4.5",
  "timeout_seconds": 20
}

安全边界

不在输入、输出、日志或 Skill 包中保存/返回 access token、refresh token、ID token、Authorization header、邮箱、subject 或原始文件名。
账号只使用稳定的短哈希 account_ref 表示。
带凭据的额度请求只允许访问固定的 cli-chat-proxy.grok.com/v1/billing、/v1/billing?format=credits 和回退 /v1/responses；OAuth 刷新只允许访问 xAI OIDC discovery 返回的 *.x.ai HTTPS endpoint。
OAuth 刷新只在内存中生效，不修改 CLIProxyAPI 登录态。
不读取非 xAI/Grok 类型的 auth 文件。

辅助脚本执行

Skill 本体是本说明文档。确需调用包内辅助脚本时，在 Skill 包根目录使用相对路径执行；运行宿主负责切换到包根目录并把所需变量注入当前子进程。

printf '%s' '{"skill_action":"<动作>"}' | python3 run.py

输入必须是 JSON 对象。写操作仍按本文档中的确认规则执行。

动作	用途
`status`	Discover local xAI OAuth auth files and report only redacted account metadata.
`query`	Read detailed Billing quota first; fall back to a minimal Grok probe only when Billing data is unavailable.