{"id":51652442,"url":"https://github.com/futureppo/grokcli2api-go","last_synced_at":"2026-07-17T08:01:34.435Z","repository":{"id":370923647,"uuid":"1297544782","full_name":"Futureppo/grokcli2api-go","owner":"Futureppo","description":"OpenAI- and Anthropic-compatible API gateway for Grok CLI with multi-account OAuth pooling, streaming, retries, and model-aware scheduling.","archived":false,"fork":false,"pushed_at":"2026-07-13T12:45:29.000Z","size":249,"stargazers_count":17,"open_issues_count":0,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-14T05:25:03.525Z","etag":null,"topics":["anthropic-api","anthropic-compatible","api-gateway","api-proxy","docker","golang","grok","grok-api","grok-cli","llm-gateway","multi-account","oauth","openai-api","openai-compatible","self-hosted","sse","streaming","xai","xai-api"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Futureppo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-11T15:09:48.000Z","updated_at":"2026-07-13T12:45:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Futureppo/grokcli2api-go","commit_stats":null,"previous_names":["futureppo/grokcli2api-go"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Futureppo/grokcli2api-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Futureppo%2Fgrokcli2api-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Futureppo%2Fgrokcli2api-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Futureppo%2Fgrokcli2api-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Futureppo%2Fgrokcli2api-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Futureppo","download_url":"https://codeload.github.com/Futureppo/grokcli2api-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Futureppo%2Fgrokcli2api-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35493172,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-15T02:00:06.706Z","response_time":131,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic-api","anthropic-compatible","api-gateway","api-proxy","docker","golang","grok","grok-api","grok-cli","llm-gateway","multi-account","oauth","openai-api","openai-compatible","self-hosted","sse","streaming","xai","xai-api"],"created_at":"2026-07-14T05:01:37.596Z","updated_at":"2026-07-15T06:00:57.949Z","avatar_url":"https://github.com/Futureppo.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# grokcli2api-go\n\n**将 Grok CLI 上游能力转换为 OpenAI 与 Anthropic 兼容 API**\n\n轻量、可部署、支持流式响应与多账号调度的 Go 兼容层\n\n[![CI](https://github.com/Futureppo/grokcli2api-go/actions/workflows/ci.yml/badge.svg)](https://github.com/Futureppo/grokcli2api-go/actions/workflows/ci.yml)\n[![Go Version](https://img.shields.io/badge/Go-1.23%2B-00ADD8?logo=go\u0026logoColor=white)](https://go.dev/)\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-663399.svg)](LICENSE)\n[![Container](https://img.shields.io/badge/GHCR-grokcli2api--go-2496ED?logo=docker\u0026logoColor=white)](https://github.com/Futureppo/grokcli2api-go/pkgs/container/grokcli2api-go)\n\n[一键部署](#一键部署linux) · [快速开始](#快速开始) · [API 兼容性](#api-兼容性) · [配置说明](#配置说明) · [接口一览](#接口一览) · [参与贡献](#开发与贡献)\n\n**简体中文** · [English](README_EN.md)\n\n\u003c/div\u003e\n\n---\n\n`grokcli2api-go` 是一个使用 Go 编写的非官方 API 兼容服务。它将 Grok CLI 使用的上游接口转换为 OpenAI Chat Completions、OpenAI Responses 与 Anthropic Messages 格式，让现有应用通常只需调整 API Base URL 即可接入。\n\n项目运行时仅依赖 Go 标准库，提供多账号 OAuth 凭证池、自动刷新、模型发现、会话亲和、失败重试与容量背压等能力，适合本地开发、内网服务和容器化部署。\n\n\u003e [!IMPORTANT]\n\u003e 本项目是非官方兼容层，与 xAI、X、OpenAI 或 Anthropic 均无隶属或合作关系。使用者应自行遵守相关服务条款，并承担使用非公开上游接口可能产生的兼容性、可用性与账号风险。\n\n## 核心能力\n\n| 类别 | 能力 |\n| --- | --- |\n| API 兼容 | OpenAI Chat Completions、OpenAI Responses、Anthropic Messages、Grok CLI 原生 Responses 透传 |\n| 响应模式 | 流式 SSE 与非流式响应，兼容常见 SDK 和 HTTP 客户端 |\n| 凭证管理 | 多账号 OAuth 凭证池、自动刷新、目录热加载、刷新结果原子写回 |\n| 智能调度 | 账号轮询、会话亲和、按模型能力调度、失败重试与额度冷却 |\n| 并发治理 | 账号级并发上限与容量背压，降低高并发场景下的 429 重试风暴 |\n| 模型发现 | 按账号获取上游模型目录，缓存、聚合并输出去重后的模型列表 |\n| 访问保护 | 可配置一个或多个本地 API Key，兼容 Bearer、`x-api-key` 与 `api-key` 请求头 |\n| 网络支持 | HTTP、HTTPS、SOCKS5、SOCKS5H 出站代理及标准 `NO_PROXY` 规则 |\n| 部署体验 | 单一二进制、优雅退出、Docker 多阶段构建与 Docker Compose 编排 |\n\n## 工作原理\n\n```mermaid\nflowchart LR\n    A[OpenAI / Anthropic 客户端] --\u003e B[可选的本地 API Key 鉴权]\n    B --\u003e C[协议转换与流式适配]\n    C --\u003e D[模型感知的账号调度器]\n    D --\u003e E1[OAuth 账号 A]\n    D --\u003e E2[OAuth 账号 B]\n    D --\u003e E3[OAuth 账号 N]\n    E1 --\u003e F[Grok CLI 上游]\n    E2 --\u003e F\n    E3 --\u003e F\n```\n\n针对不同订阅类型优化，每个请求只会调度到声明支持目标模型的有效账号。\n\n## API 兼容性\n\n| 协议 | 接口 | 流式 | 非流式 |\n| --- | --- | :---: | :---: |\n| OpenAI | `POST /v1/chat/completions` | ✓ | ✓ |\n| OpenAI | `POST /v1/responses` | ✓ | ✓ |\n| Anthropic | `POST /v1/messages` | ✓ | ✓ |\n| OpenAI | `GET /v1/models` | — | ✓ |\n\n兼容层会尽可能保留常用的请求字段、响应结构和流式事件，但不保证覆盖官方 API 的全部参数与行为。接入 New API 等 API 聚合项目时，请开启所有请求参数的**透传**。\n\n### Chat Completions 请求清洗\n\n`POST /v1/chat/completions` 会在转发前按 Grok CLI 上游结构重建请求体。支持消息、多模态文本/图片、函数工具、结构化输出、搜索参数及推理强度；常见别名会转换为上游字段，包括 `max_completion_tokens` → `max_tokens`、`functions` → `tools`、`function_call` → `tool_choice`、`user` → `user_id`。上游未声明的顶层字段和嵌套元数据会被移除，清洗路径仅在 `DEBUG` 日志中记录且不包含字段值。\n\n格式错误或会破坏消息、工具调用关系的内容会在本地返回 OpenAI 格式的 `422 invalid_request_error`。`grok-4.5*` 与 `composer` 模型族还会移除其不支持的采样惩罚和停止参数。\n\n### Responses 格式分流\n\n`POST /v1/responses` 默认按 OpenAI Responses API 处理：请求字段会按 Grok CLI 0.2.99 的 Responses 类型清洗，非流式响应与 SSE 事件会移除 Grok 原生扩展。只有请求包含明确的 Grok CLI 标识时才启用原生透传，包括 `X-XAI-Token-Auth: xai-grok-cli`、`x-grok-client-version`、已知的 Grok 客户端名称/标识，或 `grok-cli/`、`grok-shell/`、`grok-pager/` 等 User-Agent。任意或未知的 `x-grok-client-*` 值不会触发原生格式。\n\n兼容分支未指定 `store` 时按 OpenAI 默认值使用 `store: true`。后续请求可通过 `previous_response_id` 续接，并会固定回到生成该 Response 的上游账号；同一 Response ID 可派生多个独立分支。该账号亲和与工具回放状态仅保存在当前服务进程内，重启后不会恢复。显式 `store: false` 时，普通 previous ID 会由上游返回 not-found；函数工具调用可在缓存仍有效时使用最小调用结构本地续接，服务不会额外缓存用户文本或图片。\n\n兼容范围包括文本、多轮、Function/custom/namespace/tool-search、并行工具结果、Web Search、HTTPS 或 Base64 data URI 图片、`text.format.json_schema` 以及 typed SSE。错误请求返回 `400 invalid_request_error` 和准确的 `param` 路径，请求体超过 16 MiB 返回 `413`。当前不提供 `/v1/conversations`、`/v1/files`、音频、后台任务轮询、图片生成输出，以及 Web Search 之外的托管工具执行；相关参数会返回明确的 `unsupported_parameter`，不会静默忽略。\n\n`POST /v1/messages` 仍以 Anthropic 格式对外，并通过上游 Responses API 执行。Anthropic `metadata.user_id` 会映射为 Responses 的 `safety_identifier`；`stop_sequences` 由兼容层在非流式与流式响应中执行。文本、图片、图片型工具结果、并行函数工具及 Web Search server-tool 结果均会转换为对应的 Anthropic 内容块；只有请求显式启用 `thinking` 时才返回 thinking/signature 块。格式错误或断裂的 `tool_use` / `tool_result` 关系会在本地返回 Anthropic `400 invalid_request_error`。\n\n## 快速开始\n\n### 一键部署（Linux）\n\n服务器已安装 Docker 与 Docker Compose v2 时，可直接运行：\n\n```bash\nbash \u003c(curl -fsSL https://raw.githubusercontent.com/Futureppo/grokcli2api-go/main/scripts/deploy.sh)\n```\n\n脚本会检查 Docker 环境、下载 Compose 配置、创建受保护的 `.env` 和 `auths/` 目录，分别生成随机的本地 API Key 与管理员 Key，并启动及验证服务。交互执行时可以直接导入 OAuth JSON；也可以跳过本地文件，让服务以空凭证池启动，再通过管理员 API 远程上传。已有安装会保留 `.env` 与凭证，可用同一条命令完成镜像更新。\n\n无人值守部署可预先传入参数：\n\n```bash\nAUTH_FILE=/root/account.json \\\nGROK_API_KEYS='sk-change-this-to-a-strong-random-key' \\\nGROK_ADMIN_KEY='adm-use-an-independent-strong-random-key' \\\nINSTALL_DIR=/opt/grokcli2api-go \\\nbash \u003c(curl -fsSL https://raw.githubusercontent.com/Futureppo/grokcli2api-go/main/scripts/deploy.sh)\n```\n\n可选变量包括 `GROK2API_PORT`（默认 `8088`）、`INSTALL_DIR`（默认 `~/grokcli2api-go`）、`AUTH_FILE`、`GROK_API_KEYS` 与 `GROK_ADMIN_KEY`。管理员 API 默认启用；设置 `ENABLE_ADMIN_API=0` 可将其关闭，此时没有本地凭证则只初始化配置而不启动服务。\n\n\u003e [!TIP]\n\u003e 一键脚本解决的是服务部署，不会替你获取上游凭证。OAuth JSON 属于敏感信息，请只从可信来源导出，并在服务器上以最小权限保存。正式对公网开放前还应配置 HTTPS、反向代理、访问控制和限流。\n\n### 1. 准备项目\n\n运行前需要：\n\n- Docker 与 Docker Compose，或 Go 1.23 及以上版本；\n- 至少一份有效的 Grok CLI OAuth JSON 凭证，或配置管理员 Key 后再通过 API 上传；\n- 一个可写的凭证目录。\n\n```bash\ngit clone https://github.com/Futureppo/grokcli2api-go.git\ncd grokcli2api-go\ncp .env.example .env\nmkdir auths\n```\n\nWindows PowerShell：\n\n```powershell\ngit clone https://github.com/Futureppo/grokcli2api-go.git\nSet-Location grokcli2api-go\nCopy-Item .env.example .env\nNew-Item -ItemType Directory -Force auths\n```\n\n将每个账号的 OAuth JSON 文件直接放在 `auths/` 下，一份文件对应一个账号：\n\n```text\nauths/\n├── account-1.json\n├── account-2.json\n└── account-n.json\n```\n\n凭证通常需要包含可用的访问令牌、刷新信息与稳定的账号标识。服务只扫描该目录的第一层，不递归读取子目录。\n\n\u003e [!CAUTION]\n\u003e `auths/` 已被 Git 忽略，但仍应作为敏感目录妥善保管。服务会热加载凭证，并将刷新后的令牌和模型目录写回原文件，因此目录与文件必须可写。\n\n### 2. 配置本地访问密钥\n\n编辑 `.env`，将示例值替换为仅供你使用的强随机密钥：\n\n```dotenv\nGROK_API_KEYS=sk-kfcvivo50\n```\n\n本地 API Key 只用于保护当前服务，与上游 OAuth 凭证相互独立。留空可关闭访问保护，但不建议在任何可被其他设备访问的环境中这样做。\n\n### 3. 启动服务\n\n#### Docker Compose（推荐）\n\n```bash\ndocker compose up -d\ndocker compose ps\n```\n\n查看日志或停止服务：\n\n```bash\ndocker compose logs -f\ndocker compose down\n```\n\n#### 从源码运行\n\n```bash\ngo run ./cmd/grok2api\n```\n\n#### 使用预构建镜像\n\n```bash\ndocker pull ghcr.io/futureppo/grokcli2api-go:latest\ndocker run --rm -p 8088:8088 --env-file .env \\\n  -v \"$(pwd)/auths:/auths\" \\\n  -e GROK_AUTHS_DIR=/auths \\\n  ghcr.io/futureppo/grokcli2api-go:latest\n```\n\nDocker Compose 默认拉取并运行 `ghcr.io/futureppo/grokcli2api-go:latest`。每次推送都会发布 `sha-\u003ccommit\u003e` 与对应分支标签，`main` 分支还会更新 `latest`。\n\n### 4. 验证服务\n\n服务默认监听 `http://0.0.0.0:8088`。请将下面的 Key 替换为 `.env` 中的实际值：\n\n```bash\ncurl http://localhost:8088/\n\ncurl http://localhost:8088/v1/models \\\n  -H \"Authorization: Bearer sk-kfcvivo50\"\n```\n\n## 调用示例\n\n以下示例均使用 `sk-kfcvivo50` 作为占位符，请替换为自己的本地 API Key。\n\n### OpenAI Chat Completions\n\n```bash\ncurl http://localhost:8088/v1/chat/completions \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer sk-kfcvivo50\" \\\n  -d '{\n    \"model\": \"grok-4.5\",\n    \"messages\": [\n      {\"role\": \"user\", \"content\": \"Hello!\"}\n    ]\n  }'\n```\n\n### OpenAI Responses\n\n```bash\ncurl http://localhost:8088/v1/responses \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer sk-kfcvivo50\" \\\n  -d '{\n    \"model\": \"grok-4.5\",\n    \"input\": \"Explain what an API compatibility layer does.\"\n  }'\n```\n\n默认的多轮续接只需保存上一轮 ID：\n\n```bash\nFIRST_ID=$(curl -s http://localhost:8088/v1/responses \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer sk-kfcvivo50\" \\\n  -d '{\"model\":\"grok-4.5\",\"input\":\"Remember that my code is 7319.\"}' | jq -r .id)\n\ncurl http://localhost:8088/v1/responses \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer sk-kfcvivo50\" \\\n  -d \"{\\\"model\\\":\\\"grok-4.5\\\",\\\"previous_response_id\\\":\\\"$FIRST_ID\\\",\\\"input\\\":\\\"What is my code?\\\"}\"\n```\n\n图片可使用 HTTPS URL 或 Base64 data URI，并保持文本与多图的原始顺序：\n\n```json\n{\n  \"model\": \"grok-4.5\",\n  \"input\": [{\n    \"type\": \"message\",\n    \"role\": \"user\",\n    \"content\": [\n      {\"type\": \"input_text\", \"text\": \"Describe this image.\"},\n      {\"type\": \"input_image\", \"image_url\": \"https://example.com/image.png\", \"detail\": \"high\"}\n    ]\n  }]\n}\n```\n\nFunction 工具结果使用首轮返回的 `call_id`，并将首轮 Response ID 放入 `previous_response_id`：\n\n```json\n{\n  \"model\": \"grok-4.5\",\n  \"previous_response_id\": \"resp_...\",\n  \"input\": [{\"type\": \"function_call_output\", \"call_id\": \"call_...\", \"output\": \"sunny, 26 C\"}],\n  \"tools\": [{\"type\": \"function\", \"name\": \"get_weather\", \"parameters\": {\"type\": \"object\", \"properties\": {\"city\": {\"type\": \"string\"}}, \"required\": [\"city\"]}}]\n}\n```\n\n### Anthropic Messages\n\n```bash\ncurl http://localhost:8088/v1/messages \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-api-key: sk-kfcvivo50\" \\\n  -H \"anthropic-version: 2023-06-01\" \\\n  -d '{\n    \"model\": \"grok-4.5\",\n    \"max_tokens\": 512,\n    \"messages\": [\n      {\"role\": \"user\", \"content\": \"Hello!\"}\n    ]\n  }'\n```\n\n未设置 `GROK_API_KEYS` 或 `GROK_API_KEY` 时，应移除示例中的本地 API Key 请求头。\n\n## 会话亲和与账号调度\n\n当多个客户端共享同一个本地 API Key 时，建议为每段会话发送稳定且不包含敏感信息的标识：\n\n```http\nX-Grok-Session-ID: conversation-123\n```\n\n服务也会依次识别以下字段作为亲和标识：\n\n- OpenAI `previous_response_id`\n- OpenAI `prompt_cache_key`\n- OpenAI `user`\n- Anthropic `metadata.user_id`\n\n本地 API Key 与客户端 IP 不会被用作账号亲和标识。亲和关系仅保存在内存中，并受 TTL 与容量上限控制。\n\n## 配置说明\n\n程序会从当前工作目录的 `.env` 文件中加载尚未设置的环境变量。完整模板与高级客户端标识选项见 [`.env.example`](.env.example)。\n\n### 服务配置\n\n| 环境变量 | 未设置时的默认值 | 说明 |\n| --- | --- | --- |\n| `GROK2API_HOST` | `0.0.0.0` | 服务监听地址 |\n| `GROK2API_PORT` | `8088` | 服务监听端口 |\n| `GROK2API_LOG_LEVEL` | `INFO` | 日志等级：`DEBUG`、`INFO`、`WARN` 或 `ERROR` |\n| `GROK_API_KEYS` | 空 | 逗号分隔的本地访问密钥，可为不同客户端分配独立 Key |\n| `GROK_API_KEY` | 空 | 单个本地访问密钥的兼容别名 |\n| `GROK_ADMIN_KEY` | 空 | 独立的管理员密钥；设置后启用远程凭证管理并允许空凭证池启动 |\n\n启用本地访问保护后，受保护接口接受以下任一种请求头：\n\n- `Authorization: Bearer \u003ckey\u003e`\n- `x-api-key: \u003ckey\u003e`\n- `api-key: \u003ckey\u003e`\n\n管理员密钥与普通 API Key 相互独立。管理接口接受 `Authorization: Bearer \u003cadmin-key\u003e` 或 `X-Admin-Key: \u003cadmin-key\u003e`，且只应通过 HTTPS 和受限网络暴露。上传凭证可以直接发送 JSON：\n\n```bash\ncurl http://localhost:8088/v1/admin/credentials \\\n  -H \"Authorization: Bearer $GROK_ADMIN_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  --data-binary @auth.json\n```\n\n也可以使用文件表单：\n\n```bash\ncurl http://localhost:8088/v1/admin/credentials \\\n  -H \"X-Admin-Key: $GROK_ADMIN_KEY\" \\\n  -F \"file=@auth.json;type=application/json\"\n```\n\n服务端根据凭证中的稳定账号标识生成脱敏 ID；重复上传同一账号会原子覆盖原凭证。上传后会立即尝试发现模型，临时探测失败不会删除已经保存的凭证。\n\n列出脱敏后的凭证状态：\n\n```bash\ncurl http://localhost:8088/v1/admin/credentials \\\n  -H \"X-Admin-Key: $GROK_ADMIN_KEY\"\n```\n\n删除凭证时使用列表返回的 24 位脱敏 ID：\n\n```bash\ncurl -X DELETE http://localhost:8088/v1/admin/credentials/\u003ccredential-id\u003e \\\n  -H \"X-Admin-Key: $GROK_ADMIN_KEY\"\n```\n\n管理接口响应带有 `Cache-Control: no-store`。上传文件限制为 1 MiB，服务会校验 JSON、使用账号身份生成保存路径并以 `0600` 权限原子写入，不会采用客户端提供的文件名。建议优先在服务器本机或 SSH 隧道中管理；如需跨网络访问，必须使用 HTTPS，并在反向代理层限制来源和频率。\n\n### 凭证池与调度\n\n| 环境变量 | 未设置时的默认值 | 说明 |\n| --- | --- | --- |\n| `GROK_AUTHS_DIR` | `./auths` | 非递归扫描的可写 OAuth JSON 目录 |\n| `GROK_AUTHS_RELOAD_INTERVAL` | `30s` | 凭证目录热加载周期 |\n| `GROK_AUTH_REFRESH_CONCURRENCY` | `4` | OAuth 刷新的最大并发数 |\n| `GROK_ACCOUNT_MAX_INFLIGHT` | `16` | 每账号最大上游在途请求数，超出后等待可用容量 |\n| `GROK_MODELS_REFRESH_INTERVAL` | `6h` | 每个账号模型目录的刷新周期 |\n| `GROK_RETRY_MAX_ATTEMPTS` | `3` | 单个请求最多尝试的不同账号数 |\n| `GROK_RETRY_BASE_DELAY` | `200ms` | 可重试网络错误与上游 5xx 错误的基础退避时间 |\n| `GROK_RATE_LIMIT_COOLDOWN` | `1m` | 上游 429 未提供 `Retry-After` 时的冷却时间 |\n| `GROK_QUOTA_COOLDOWN` | `24h` | 额度耗尽后的默认冷却时间 |\n| `GROK_AFFINITY_TTL` | `1h` | 内存会话亲和关系的有效期 |\n| `GROK_AFFINITY_MAX_ENTRIES` | `100000` | 会话亲和缓存的容量上限 |\n\n免费模型额度按账号与模型隔离；账号支出额度耗尽时，整个账号会进入冷却。\n\n### 上游与网络\n\n| 环境变量 | 未设置时的默认值 | 说明 |\n| --- | --- | --- |\n| `GROK_CHAT_PROXY_BASE_URL` | `https://cli-chat-proxy.grok.com` | Grok CLI 上游地址 |\n| `GROK_CHAT_PROXY_VERSION` | `v1` | 上游 API 版本 |\n| `GROK_STREAM_COMPRESSION` | `identity` | `identity` 避免 gzip 缓冲 SSE；`gzip` 用于兼容回退 |\n| `GROK_PROXY_URL` | 空 | 出站代理，支持 HTTP(S)、SOCKS5 与 SOCKS5H |\n| `GROK_NO_PROXY` | 空 | 逗号分隔的代理绕过规则 |\n| `GROK_TLS_INSECURE_SKIP_VERIFY` | `false` | 跳过上游 TLS 验证，仅限受控调试环境 |\n\n未设置 `GROK_PROXY_URL` 时，程序遵循标准的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 与 `NO_PROXY` 环境变量。\n\n例如通过本机 HTTP 代理 `7890` 访问上游：\n\n```dotenv\nGROK_PROXY_URL=http://127.0.0.1:7890\nGROK_NO_PROXY=localhost,127.0.0.1\n```\n\n命令行参数 `-host` 和 `-port` 可覆盖对应环境变量，`-version` 用于输出当前版本：\n\n```bash\ngo run ./cmd/grok2api -host 127.0.0.1 -port 8088\ngo run ./cmd/grok2api -version\n```\n\n## 接口一览\n\n### 兼容接口\n\n| 方法 | 路径 | 鉴权 | 说明 |\n| --- | --- | :---: | --- |\n| `GET` | `/` | 否 | 服务名称、版本与项目地址 |\n| `GET` | `/v1/models` | 可选 | 所有有效账号模型目录的去重并集 |\n| `GET` | `/v1/models/{model_id}` | 可选 | 指定模型的详情 |\n| `GET` | `/v1/auth/api-key` | 否 | 本地 API Key 保护状态 |\n| `POST` | `/v1/chat/completions` | 可选 | OpenAI Chat Completions 兼容接口 |\n| `POST` | `/v1/responses` | 可选 | OpenAI Responses 兼容接口 |\n| `POST` | `/v1/messages` | 可选 | Anthropic Messages 兼容接口 |\n\n“可选”表示仅在配置了本地 API Key 时需要鉴权。\n\n### 管理员凭证接口\n\n仅在设置 `GROK_ADMIN_KEY` 后启用，普通 API Key 无法访问。列表响应不会包含账号标识、文件路径、客户端 ID 或 Token。\n\n| 方法 | 路径 | 说明 |\n| --- | --- | --- |\n| `GET` | `/v1/admin/credentials` | 列出脱敏的凭证状态和模型目录 |\n| `POST` | `/v1/admin/credentials` | 上传或覆盖 JSON 凭证，支持 JSON 请求体和 multipart `file` 字段 |\n| `DELETE` | `/v1/admin/credentials/{id}` | 删除凭证并立即从调度池移除 |\n\n### Grok 只读透传接口\n\n| 方法 | 路径 |\n| --- | --- |\n| `GET` | `/v1/grok/settings` |\n| `GET` | `/v1/grok/user` |\n| `GET` | `/v1/grok/billing` |\n| `GET` | `/v1/grok/mcp/configs` |\n| `GET` | `/v1/grok/mcp/tools/list` |\n| `GET` | `/v1/grok/feedback/config` |\n\n启动时，服务会读取凭证 JSON 中缓存的模型目录，并为缺失目录或超过刷新周期的账号请求上游 `/v1/models`。新增账号也会在目录热加载后自动完成模型发现。规范化后的 `models` 与 `models_updated_at` 字段会持久化到对应凭证文件，并在刷新令牌时保留。\n\n实际支持的模型始终以上游账号返回结果为准。调用生成接口前建议先查询 `/v1/models`，并使用返回的准确模型 ID。\n\n## Docker 与镜像说明\n\n项目镜像采用多阶段构建：构建阶段执行完整测试并生成无 CGO 的二进制，运行阶段使用非 root 用户和精简 Alpine 基础镜像。Compose 配置还默认启用只读根文件系统、能力移除、`no-new-privileges` 与健康检查。\n\n本地 `.env` 和 `auths/` 始终作为外部配置与凭证数据使用，重新构建或创建容器不会将它们写入镜像。\n\n## 安全建议\n\n- 切勿提交或公开 OAuth Token、API Key、认证文件及未脱敏日志。\n- 对外提供服务前，务必配置 `GROK_API_KEYS`，并在反向代理层启用 HTTPS、访问控制和限流。\n- 启用 `GROK_ADMIN_KEY` 时应使用独立的强随机密钥，并额外限制管理接口的来源地址和请求频率。\n- 为凭证目录设置最小必要文件权限，并限制可访问该目录的系统用户。\n- 除非处于受控调试环境，否则不要启用 `GROK_TLS_INSECURE_SKIP_VERIFY`。\n- 不要把会话 ID、用户邮箱或其他敏感数据直接用作亲和标识。\n- 安全漏洞请通过 [GitHub Security Advisories](https://github.com/Futureppo/grokcli2api-go/security/advisories/new) 私下报告。\n\n## 开发与贡献\n\n### 本地检查\n\n```bash\ngofmt -w path/to/changed.go\ngo test ./...\ngo test -race ./...\ngo vet ./...\ngo build ./cmd/grok2api\n```\n\n\u003e `go test -race ./...` 需要当前平台支持 Go Race Detector；项目 CI 会在 Linux 环境执行该检查。\n\n### 真实负载测试\n\n项目提供默认跳过的真实上游负载测试，可报告响应头、首事件、首段非空文本、完成时间与样本覆盖率：\n\n```bash\nGROK_LIVE_LOAD=1 GROK_LOAD_MODEL=grok-4 GROK_LOAD_STREAM=1 \\\nGROK_LOAD_WARMUP=4 GROK_LOAD_CONCURRENCY=4 GROK_LOAD_REQUESTS=16 \\\nGROK_LOAD_API=responses GROK_LOAD_AFFINITY=cache \\\ngo test ./internal/server -run TestLiveGenerationLoad -v\n```\n\n- `GROK_LOAD_API`：`responses`、`chat` 或 `anthropic`\n- `GROK_LOAD_AFFINITY`：`none`、`session` 或 `cache`\n- `GROK_LOAD_INPUT_BYTES`：生成指定字节数的测试输入\n\n设置 `GROK2API_LOG_LEVEL=DEBUG` 可查看不包含凭证、正文和会话标识的分段耗时日志。\n\n提交代码前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。Bug 与功能建议可通过 [GitHub Issues](https://github.com/Futureppo/grokcli2api-go/issues) 提交；Pull Request 应保持主题聚焦，并为协议转换、流式事件或错误处理等改动补充测试。\n\n## 许可证\n\n本项目基于 [GNU Affero General Public License v3.0](LICENSE) 发布。使用、修改或分发本项目时，请遵守许可证中的相应义务。\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n如果这个项目对你有帮助，欢迎提交 Issue、参与改进或为仓库点亮 Star⭐。\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffutureppo%2Fgrokcli2api-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffutureppo%2Fgrokcli2api-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffutureppo%2Fgrokcli2api-go/lists"}