先说结论#

你需要的东西只有三样:

你要的从哪来长什么样
接口地址控制台文档形如 https://xxx/v1
密钥控制台创建一长串字符,只显示一次
模型 ID模型广场形如 deepseek-chat,每家的名字不一样

把这三样填进任何支持 OpenAI 接口的工具,就算接好了。不需要改代码,不需要装 SDK 才能开始。

为什么推荐中转站而不是一个个去官方注册

一个 key 通多家模型,换模型不用换账单;国内直连不用折腾网络;按量计费,试错成本低。代价是多一层转发,极少数场景会有几十毫秒的额外延迟。

十分钟跑通#

第一步:注册并完成实名#

手机用相机对着下面这张图,或者在电脑上点这个链接:诸葛智算注册入口。走这条路注册会自动绑定站长渠道,活动折扣按站内算。

诸葛智算注册入口,手机相机可直接识别

国内平台按规需要实名,这一步绕不过去,准备身份证即可。

注册后先在站内找「模型广场」和「文档」两个入口,后面要用。

第二步:创建密钥#

在控制台的「API 密钥」页面新建一个。两个习惯,从第一天就养成:

  1. 一个用途一个 key。桌面端、脚本、群机器人分开建。哪天某个泄露了,只吊销那一个。
  2. 创建后立刻粘贴到密码管理器。大多数平台只完整显示一次。

第三步:用 curl 验证#

不用装任何东西,终端里直接跑。把三个尖括号里的内容换成你自己的:

bash
export ZHUGE_KEY="<你的key>"
export ZHUGE_BASE="https://zhugeai.cn/v1"
export MODEL="<模型广场里复制的模型ID>"

curl -s "$ZHUGE_BASE/chat/completions" \
  -H "Authorization: Bearer $ZHUGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "messages": [{"role": "user", "content": "只回复两个字:通了"}],
    "max_tokens": 20
  }'

验收标准:返回的 JSON 里有 choices[0].message.content,内容是「通了」或者类似的回答。

如果这一步就报错,先别往下走,直接看本文最后一节「报错对号入座」。

第四步:固定下来,别再手打#

把变量写进 ~/.zshrc(或 ~/.bashrc),新开终端就能用。不要把 key 写进任何会被提交的文件。

bash
# ~/.zshrc
export ZHUGE_KEY="<你的key>"
export ZHUGE_BASE="https://zhugeai.cn/v1"
bash
source ~/.zshrc && echo "${ZHUGE_KEY:0:6}..."   # 只回显前 6 位,确认加载了

接到你自己的工具里#

Python(官方 openai 库)#

中转站兼容 OpenAI 协议,所以官方 SDK 直接能用,只改 base_url:

python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ZHUGE_KEY"],
    base_url=os.environ["ZHUGE_BASE"],
)

resp = client.chat.completions.create(
    model=os.environ["MODEL"],
    messages=[
        {"role": "system", "content": "你是简洁的中文助手。"},
        {"role": "user", "content": "用一句话解释什么是 token"},
    ],
)
print(resp.choices[0].message.content)

Node.js#

js
import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env['ZHUGE_KEY'],
  baseURL: process.env['ZHUGE_BASE'],
})

const res = await client.chat.completions.create({
  model: process.env.MODEL,
  messages: [{ role: 'user', content: '你好' }],
})
console.log(res.choices[0].message.content)

各种客户端(WorkBuddy / DSH / Hermes / 桌宠)#

它们要的都是同一组东西:接口地址 + 密钥 + 模型名。区别只在「填在哪」。

  • WorkBuddy:设置里找「模型服务 / API」相关项,见 WorkBuddy 教程
  • DSH:profile 的 provider 配置,见 DSH 教程
  • Hermes:hermes setup model 或 config.yaml 的 providers,见 Hermes 教程
  • 大肥鱼桌宠:首次启动会让你填,见 大肥鱼教程

模型 ID 别照抄网上的

每个平台的模型命名都不一样,同一个月底也可能改名。永远从你控制台的模型广场复制,不要用教程里的示例。看到 model not found,九成是这里错了。

怎么不花冤枉钱#

按量计费的意思是:你不注意,它就一直烧。三个立刻能做的动作:

1. 按任务分级用模型#

任务用哪档理由
分类、打标签、纠错小模型一次几分钱,够用
日常问答、写草稿中档性价比区间
长文推理、代码重构大模型只在这类任务上开

同一个产品里混着用,是最省的做法。别所有请求都打最贵的那个。

2. 能缓存就缓存#

系统提示词、固定知识、工具说明——这些每次都一样。支持 prompt 缓存的模型,命中后单价通常低一个量级。把「不变的」放前面,「变的」放后面,是缓存命中的前提。

3. 每个项目单独限额#

控制台里给 key 设日限额。写脚本的时候也会更小心——限额一到就失败,比月底看到账单好。

一个反直觉的经验

大多数人的成本不在模型单价,在重复调用。同一个问题问五遍、把整篇文档反复塞进上下文,比换更贵的模型烧得多。先优化调用次数,再优化单价。

报错对号入座#

状态码大概率原因怎么修
401key 错、过期、或复制时带了空格/换行重新复制,注意别带引号;确认 Bearer 后面有一个空格
403没实名、没开通该模型、或余额不足看控制台提示,补实名或充值
404接口路径错(少 /v1)或模型 ID 不存在路径用文档给的原文;模型名从模型广场复制
429触发限流或额度上限降并发、加退避重试;看是不是设了日限额
5xx上游模型厂商抖动等几秒重试;连续失败就换模型 ID 试
返回空内容max_tokens 太小,或触发了内容过滤调大 max_tokens,换个问法

排查顺序建议固定成:先 curl,再 SDK,最后你自己的代码。curl 通了说明 key 和网络没问题,问题在后两层;curl 不通就别在代码里找。

安全三条#

  1. key 不进仓库。.env 加进 .gitignore,仓库里只放 .env.example 占位。
  2. 截图先打码。控制台页面、终端回显、报错信息里都可能带 key 的前缀和后缀。
  3. 泄露立刻吊销。别抱侥幸,重新建一个只要十秒。
bash
# .gitignore
.env
.env.*
!.env.example

验收清单#

这五条都打勾,再去看下一篇。否则后面每一篇都会卡在同一个地方。