Grok Gateway

本地运行的 Grok 协议网关服务。读取本机已登录的 Grok CLI 凭据（~/.grok/auth.json），请求直连 Grok CLI 产品端点（cli-chat-proxy.grok.com），直接使用 SuperGrok / X Premium+ 订阅的周期额度，并转换为标准的 OpenAI (/v1/chat/completions)、Anthropic (/v1/messages) 与 Responses (/v1/responses) 协议端点，供外部开发工具调用。

---

架构原理

┌──────────────────────────────────────────────┐
│ 外部工具: Cursor / Claude Code / OpenAI SDK  │
└──────────────────────┬───────────────────────┘
                       │ OpenAI / Anthropic 协议请求
                       ▼
┌──────────────────────────────────────────────┐
│ Grok Gateway (默认监听 127.0.0.1:8788)        │
│ ├─ 协议转码器 (IR 中间表示与 SSE 流转换)      │
│ ├─ 凭据管理器 (读取 ~/.grok/auth.json 并续期) │
│ └─ Web 管理控制台 (支持明暗色与主题色切换)     │
└──────────────────────┬───────────────────────┘
                       │ 走 cli-chat-proxy.grok.com
                       ▼
┌──────────────────────────────────────────────┐
│ Grok 官方服务 (扣除 SuperGrok 订阅周期配额)   │
└──────────────────────────────────────────────┘

---

主要功能

• 三协议无感转换：对外统一暴露标准 OpenAI、Anthropic 与 Responses 接口，内部通过自研 IR（中间表示）进行协议双向映射与 SSE 流式重写，完整保留思考过程（Reasoning）与工具调用。
• 本地凭据自动续期：读取 Grok CLI 存储的访问令牌，并在 Token 即将到期前自动使用 refresh_token 进行续期和回写，无需手动配置外部 API Key。
• 配额与状态监控：控制台直观呈现 SuperGrok 周期用量百分比、配额重置倒计时与上游模型列表。
• 轻量 Web 控制台：基于 Alpine.js + Tailwind CSS，纯本地内置离线依赖，支持深色 / 浅色模式与 7 套主题配色切换，提供在线演练、连通测试与请求日志。

---

快速开始

前置要求

• Python 3.11+
• 本机已安装并完成登录的 Grok CLI（即本地已存在 ~/.grok/auth.json 且状态有效）

启动服务

Windows： 双击运行 start.bat，或在命令行中运行：

python -m app.main

macOS / Linux：

chmod +x start.sh
./start.sh

Docker 启动：

cp config.example.json config.json
docker compose up -d --build

服务启动后，在浏览器访问控制台：http://127.0.0.1:8788。

---

客户端接入方式

1. Cursor IDE

• OpenAI API Key: sk-local（或网关配置的 local_api_key）
• Base URL: http://127.0.0.1:8788/v1
• Model: grok-4.6、grok-4.5 或 grok-4-fast

2. Claude Code

在终端导出环境变量即可直接使用：

export ANTHROPIC_BASE_URL=http://127.0.0.1:8788
export ANTHROPIC_AUTH_TOKEN=sk-local
claude

3. Python OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8788/v1",
    api_key="sk-local",
)

response = client.chat.completions.create(
    model="grok-4.6",
    messages=[{"role": "user", "content": "你好"}],
    stream=True,
)

for chunk in response:
    content = chunk.choices[0].delta.content or ""
    print(content, end="", flush=True)

4. cURL

curl http://127.0.0.1:8788/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-local" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "你好"}]
  }'

---

配置说明

配置文件为 config.json（可参考 config.example.json）：

{
  "server": {
    "host": "127.0.0.1",
    "port": 8788,
    "local_api_key": "sk-local",
    "admin_api_key": "",
    "default_model": "grok-4.6",
    "upstream_base_url": "https://cli-chat-proxy.grok.com/v1",
    "upstream_mode": "chat_completions",
    "allow_unknown_models": true
  }
}

配置参数	说明	默认值
host	监听地址，公开绑定时必须设置 local_api_key	127.0.0.1
port	监听端口	8788
local_api_key	入站请求鉴权 Key，留空且仅绑定本机时免鉴权	sk-local
admin_api_key	管理接口鉴权 Key，留空则沿用 local_api_key	""
upstream_base_url	Grok CLI 后端代理端点	https://cli-chat-proxy.grok.com/v1
upstream_mode	上游通信模式 (chat_completions 或 responses)	chat_completions
default_model	默认模型	grok-4.6

---

安全注意事项

1. 本网关读取的是本机个人的 Grok CLI 登录凭据，严禁直接暴露在公网环境下。
2. 若将服务绑定至非本地回环地址（如 0.0.0.0），服务会进行安全拦截，必须配置强密码形式的 local_api_key 方可对外响应。