先验证权限，再完成第一次调用

基础地址与身份验证

API 根地址：https://www.gwgear.cn/v1

每个请求都需要请求头：Authorization: Bearer 您的API_KEY

1. 先读取此 Key 的可用模型

模型白名单由每个 Key 的套餐或管理员配置决定。第一次调用前，先获取实际可用模型；下面命令适用于 Windows PowerShell。

# 仅当前 PowerShell 窗口有效；不要把真实 Key 保存进脚本
$env:GWGEAR_API_KEY = "请粘贴你的 gw_ Key"

# 在 Windows PowerShell 中请明确使用 curl.exe，避免 shell 别名行为差异
curl.exe "https://www.gwgear.cn/v1/models" `
  -H "Authorization: Bearer $env:GWGEAR_API_KEY"

从返回结果的 data[].id 里复制模型 ID。公开价格请查看模型广场；价格页展示不等于你的 Key 一定具有该模型权限。

2. Chat Completions：POST /v1/chat/completions

适用于已经使用 OpenAI Chat Completions 格式的服务端应用。示例中的 qwen-plus 必须替换为上一步返回、且你的 Key 已授权的模型 ID。

# PowerShell：先在当前窗口设置环境变量
$env:GWGEAR_API_KEY = "请粘贴你的 gw_ Key"

curl.exe "https://www.gwgear.cn/v1/chat/completions" `
  -H "Authorization: Bearer $env:GWGEAR_API_KEY" `
  -H "Content-Type: application/json" `
  -d '{"model":"qwen-plus","messages":[{"role":"user","content":"你好，请回复连接成功"}]}'

# PowerShell：推荐，稳定处理中文 JSON
$env:GWGEAR_API_KEY = "请粘贴你的 gw_ Key"
$body = @{
  model = "qwen-plus"
  messages = @(
    @{ role = "user"; content = "你好，请回复连接成功" }
  )
} | ConvertTo-Json -Depth 5 -Compress

$response = Invoke-RestMethod -Uri "https://www.gwgear.cn/v1/chat/completions" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $env:GWGEAR_API_KEY" } `
  -ContentType "application/json; charset=utf-8" `
  -Body ([System.Text.Encoding]::UTF8.GetBytes($body))

$response.choices[0].message.content

const response = await fetch("https://www.gwgear.cn/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.GWGEAR_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "qwen-plus",
    messages: [{ role: "user", content: "你好，请回复连接成功" }]
  })
});
console.log(await response.json());

import os, requests

response = requests.post(
    "https://www.gwgear.cn/v1/chat/completions",
    headers={"Authorization": "Bearer " + os.environ["GWGEAR_API_KEY"]},
    json={"model": "qwen-plus", "messages": [{"role": "user", "content": "你好，请回复连接成功"}]},
    timeout=30,
)
print(response.json())

传入 stream: true 时，接口以 Server-Sent Events 返回 OpenAI 兼容的分段事件；如不需要流式响应，请省略 stream 或设为 false。无论哪种方式，都请在服务端处理超时和非 2xx 响应，并保留 x-request-id。

3. Responses：POST /v1/responses

适用于以 Responses wire API 工作的 Codex 或 Agent 集成。当前兼容层支持文本输入和自定义 function 工具；不支持服务端会话、previous_response_id、后台任务或图像/音频等多模态输入。请求请显式设置 store: false。

# Windows PowerShell：Responses 文本调用
$env:GWGEAR_API_KEY = "请粘贴你的 gw_ Key"
$body = @{
  model = "qwen-plus"
  input = "你好，请回复连接成功"
  store = $false
} | ConvertTo-Json -Depth 5 -Compress

$response = Invoke-RestMethod -Uri "https://www.gwgear.cn/v1/responses" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $env:GWGEAR_API_KEY" } `
  -ContentType "application/json; charset=utf-8" `
  -Body ([System.Text.Encoding]::UTF8.GetBytes($body))

$response.output_text

计费说明

费用按输入、输出、缓存读取和缓存写入 Token 分别计算；阶梯模型还会按输入或输出 Token 区间选择费率，最后向上取整到人民币分。当前聊天接口仅开放已覆盖计费的能力；不接受带独立费用的上游内置工具，Gemini 暂只开放文本输入，Qwen Plus 暂只开放非思考模式。响应头包含：

x-request-id: 本次请求编号
x-gwgear-charge-cents: 本次实际扣费（分）
x-gwgear-balance-cents: 扣费后余额（分）

常见错误

安全建议

为每个项目使用独立 Key；发现泄露时立即在客户控制台重置；生产环境设置月度上限和模型白名单；日志中只记录 Key 前缀，不记录完整 Key。出现报错时，把 x-request-id 和发生时间提供给支持人员即可。

Codex 与 Agent 的安全接入

1. 先在配置助手验证 Key，并选择实际返回的可用模型；它会生成与该 Key 权限相符的样例。
2. 只在受信任的本机或服务器会话中设置 GWGEAR_API_KEY 环境变量。不要把 Key 填入项目源码、config.toml、聊天消息或远程任务参数。
3. 若你的 Codex 或 Agent 支持自定义模型提供商，使用 API 根地址 https://www.gwgear.cn/v1 和 Responses 协议；先在测试环境完成一次最小文本调用，再逐步启用工具。
4. 为每个 Agent 单独配置 Key、模型白名单和月度限额。Agent 发生异常时先停用或重置该 Agent 专用 Key，不要影响其他项目。

# 仅作配置字段示意；不要把真实 Key 写进此文件
[model_providers.gwgear]
base_url = "https://www.gwgear.cn/v1"
env_key = "GWGEAR_API_KEY"
wire_api = "responses"

打开配置助手 下载最小 Starter

开发者 Starter

可下载无第三方依赖的 Node.js 最小示例，先完成一次可追溯的真实调用，再接入你的业务服务。