Grokbuild Proxy

grokbuild-proxy

简体中文 | English

grokbuild-proxy 是一个本地、自托管的协议兼容代理，用于将使用者本人
合法持有的 Grok Build 账号接入 Claude Code、Anthropic SDK 和
OpenAI 兼容客户端。

项目将 Anthropic Messages 请求转换到 Grok Build Responses 后端，支持
流式输出、客户端工具、结构化输出、思考强度、CPA 风格 Thinking Block、
加密推理回放和 Grok 内置 Web Search。

本项目是非官方、社区维护的技术学习与协议互操作研究项目，与 xAI、
Grok、Anthropic、OpenAI 及其关联公司无关，也未获得其授权、赞助或
认可。只能使用你本人合法持有并获准自动化操作的账号。使用本项目可能
违反相关服务条款或导致账号限制，全部风险由使用者自行承担。使用前请
阅读完整的免责声明。

功能

- Anthropic 兼容的 POST /v1/messages
- OpenAI 兼容接口：
  - POST /v1/responses
  - POST /v1/chat/completions
  - GET /v1/models
- 增量 SSE 转换，不缓冲完整响应
- 客户端函数工具和并行工具调用
- Anthropic web_search_* 映射到 Grok 内置 Web Search
- Anthropic JSON Schema 映射到 Responses text.format
- Adaptive / Manual Thinking 与思考强度兼容
- Summarized / Omitted Thinking Block
- 工具轮次间的加密 Reasoning 回放
- 多账号选择、会话粘滞、冷却和故障切换
- Grok/CPA JSON、多文件及可选 SSO 批量导入
- 全局与凭据级 HTTP(S)/SOCKS 出站代理
- 保守的自动巡检、401 确认隔离、429 冷却及可选延迟清理
- Grok Build 共享周额度主视图与原始账单诊断
- 浏览器 OAuth Device Login
- 带文件锁、原子写入和备份恢复的本地 JSON 存储
- 内嵌 Admin Web UI
- 健康检查、Readiness、Prometheus 指标、Request ID 和结构化日志
- 多平台归档、校验和、SBOM 与 GHCR 容器镜像

架构

组件边界和协议决策见 DESIGN.md。

环境要求

- Go 1.26.5 或更高版本，或者 Docker
- 使用者本人合法持有的 Grok CLI / Grok Build 账号
- 可信的本机或私有网络环境

一键安装

Linux / macOS：

Windows PowerShell：

安装脚本会自动识别系统与架构、下载最新 Release、验证 SHA-256、安装
二进制并生成本地配置。可以通过 GROKBUILD_VERSION=v0.2.0 固定版本。

源码运行

默认监听 127.0.0.1:8080。

api_key 和 admin_key 留空时，首次启动会将随机密钥写入
data/meta.json。该文件包含敏感信息，禁止提交或分享。

打开 Admin UI：

在 Admin UI 中完成浏览器登录、导入 Grok CLI 凭据、管理账号池，以及
创建或撤销客户端密钥。

建议优先使用代理自己的浏览器 Device Login。直接导入
~/.grok/auth.json 可能复制一份已经旋转或撤销的 Refresh Token。

Claude Code

也可以使用配置过的 Claude 模型别名：

通过 anthropic.model_aliases 可以把 Claude 模型映射到指定 Grok 模型。

OpenAI 兼容客户端

Docker Compose

Compose 只在宿主机发布 127.0.0.1:8080，运行状态保存在命名卷中。

可选 SSO 批量导入服务

SSO 转换 sidecar…