模型、服务、API 与客户端

新手最常见的混乱，是把模型名、网站、接口和软件混为一谈。记住一条调用链就够了：

你 → 客户端 → API 地址 + 令牌 → 服务商 → 模型 → 返回结果

1. 六个角色分别做什么

名称	通俗理解	例子	决定什么
模型	发动机	GPT、Claude、Gemini、Qwen	能力上限、速度、输入输出类型
服务商	提供发动机的人	OpenAI、Anthropic、Google 或接口平台	可用模型、额度、稳定性和计费
API	统一的调用入口	HTTP 请求与 JSON 响应	软件如何连接服务
API 地址	服务入口位置	https://api.example.com/v1	请求发到哪里
令牌	账户钥匙	sk-xxxxxxxx	谁在调用、扣谁的额度
客户端	你操作的软件	Claude Code、Codex、Cursor	工作方式、能否读文件和执行命令

同一个客户端可以连接不同服务，同一个服务可以提供多个模型，同一个模型也可能由不同客户端调用。所以“软件不好用”需要继续拆成：是客户端体验、接口连接，还是模型能力的问题。

2. Agent 又多做了什么

普通聊天通常只有“输入文字 → 返回文字”。Agent 会循环执行：

理解目标 → 制定步骤 → 调用工具 → 观察结果 → 调整计划 → 交付

工具可以是读取文件、搜索代码、运行测试、访问数据库或操作浏览器。Agent 的价值不是“更会聊天”，而是能把多个动作串成任务；风险也来自这里，因此要设置权限、审查命令并保留回滚点。

3. 一次请求里发生了什么

1. 客户端把系统规则、聊天历史、你的任务和相关文件整理成上下文。
2. 客户端携带令牌，把请求发送到 API 地址。
3. 服务商验证令牌、额度和模型权限。
4. 模型根据上下文生成结果，Agent 可能继续调用工具。
5. 服务商按输入与输出 Token、请求次数或套餐规则计费。

这解释了三个现象：历史越长通常越贵；换客户端不一定会换模型；模型正常但地址或令牌错误时仍然无法使用。

4. 配置时必须确认的五项

API 地址：是否包含文档要求的路径，例如 /v1
令牌：是否复制完整、是否还有额度、是否放在正确字段
模型名：必须与服务商实际提供的名称完全一致
协议：客户端需要 OpenAI 兼容、Anthropic 兼容，还是原生协议
网络：域名能否访问，代理是否错误接管连接

不要泄露令牌

令牌不要放进截图、聊天记录、Git 仓库或前端代码。示例统一使用 sk-xxxxxxxx；一旦误传，立即到控制台撤销并创建新令牌。

5. 出错时按层判断

现象	优先检查
command not found	客户端是否安装、PATH 是否生效
401 / Unauthorized	令牌错误、过期或未被客户端读取
404 / model not found	API 地址、模型名、协议兼容性
429 / rate limit	额度、并发、服务容量、重试间隔
能回答但不会改文件	当前是聊天模式、目录未授权或工具权限未开启
修改结果不符合项目规范	上下文不足、规则文件缺失、验收标准不清

需要完整流程时，转到《通用排错手册》。

6. 一个真实配置长什么样

把抽象的调用链落到具体配置上。多数命令行客户端通过环境变量或配置文件完成第 4 节的五项确认：

# 以 OpenAI 兼容协议接入 STJAPI 为例（令牌请使用你自己的）
export OPENAI_BASE_URL="https://你的接入地址/v1"
export OPENAI_API_KEY="sk-xxxxxxxx"        # STJAPI 控制台创建的令牌
export OPENAI_MODEL="gpt-5.6-terra"        # 必须与分组内实际模型名一致

Claude 系客户端则通常使用 ANTHROPIC_BASE_URL 与 ANTHROPIC_AUTH_TOKEN。字段名因客户端而异，但内容永远是那三样：地址、令牌、模型名。

逐项对应的常见错误：

配置项	典型错误	表现
地址	少了 /v1，或把控制台网址当接口地址	404、连接重置
令牌	复制时多了空格、用了别的平台的令牌	401
模型名	简写、大小写不一致、分组里没有该模型	404 / 无权限
协议	OpenAI 兼容客户端连了 Anthropic 协议地址	响应格式错误、客户端报解析失败

配置好之后，先用一条最小请求验证：

curl -s "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"'"$OPENAI_MODEL"'","messages":[{"role":"user","content":"ping"}]}'

返回正常 JSON 即说明调用链已通，之后的排错就可以聚焦在客户端本身。各客户端的完整安装与配置教程，见《接入实战》分类下的分步指南。