# Grok Quota

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

- **Type:** Skill
- **Install:** `agentstack add skill-uvwt-agentdock-grok-quota`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [uvwt](https://agentstack.voostack.com/s/uvwt)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [uvwt](https://github.com/uvwt)
- **Source:** https://github.com/uvwt/agentdock/tree/main/skill-sources/grok-quota
- **Website:** https://uvwt.github.io/agentdock-docs/

## Install

```sh
agentstack add skill-uvwt-agentdock-grok-quota
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 凭据。

支持以下凭据来源：

1. 官方 Grok Build CLI：`$GROK_HOME/auth.json` 或当前系统用户的 `~/.grok/auth.json`。
2. 输入 `auth_file`：一个绝对 JSON 文件路径。
3. 输入 `auth_dir`：一个绝对目录路径。
4. 环境变量 `GROK_QUOTA_AUTH_FILE`。
5. 环境变量 `GROK_QUOTA_AUTH_DIR` 或 `CLIPROXY_AUTH_DIR`。
6. 未配置显式来源时，扫描 `~/.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 目录：

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

## 输入示例

状态检查：

```json
{
  "skill_action": "status"
}
```

查询唯一账号：

```json
{
  "skill_action": "query"
}
```

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

```json
{
  "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 包根目录使用相对路径执行；运行宿主负责切换到包根目录并把所需变量注入当前子进程。

```bash
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. |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [uvwt](https://github.com/uvwt)
- **Source:** [uvwt/agentdock](https://github.com/uvwt/agentdock)
- **License:** Apache-2.0
- **Homepage:** https://uvwt.github.io/agentdock-docs/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-uvwt-agentdock-grok-quota
- Seller: https://agentstack.voostack.com/s/uvwt
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.