夜雨聆风AI 工具配置 · 2026.04.18
KEY TAKEAWAY
所有 AI 服务的配置，不管界面长什么样，真正决定"能不能用"的只有三个参数：api_key（你是谁）、base_url（找谁）、model（要什么）。三件套之外还有一堆参数——哪些必须填、哪些可以不管？看完就懂。
3
核心参数
8
扩展参数
4
排查层级
每次看到 AI 工具的 API 配置界面，是不是一头雾水？什么 base_url、api_key、model、provider……一堆术语，不知道哪些能改、哪些不能动。这篇文章把所有参数讲清楚——哪些是命根子不能碰，哪些随便填不影响。
一、API 配置的「三件套」
所有 AI 服务的配置，本质上都在回答三个问题：
● 你是谁？ → api_key（身份凭证）
● 找谁说话？ → base_url（服务地址）
● 要什么模型？ → model（模型标识）
这三个参数缺一不可，少一个或填错一个，服务就通不了。
api_key — 你是谁
一串加密字符串，证明"我有权调用这个服务"。格式通常是 sk- 开头（OpenAI）或一串 UUID。
FIXapi_key 避坑
不能少字符 — 复制时注意不要截断
不能多字符 — 不要多复制空格或换行
不能搞混 — OpenAI 的 key 不能用在 DeepSeek 上
base_url — 找谁
API 服务器的 URL，告诉客户端"去哪里找这个服务"。这是最容易搞错的参数。
▸ OpenAI 官方：https://api.openai.com/v1
▸ DeepSeek：https://api.deepseek.com
▸ 硅基流动：https://api.siliconflow.cn/v1
▸ OpenRouter：https://openrouter.ai/api/v1
FIXbase_url 最常犯的错
路径重复 — 不要把 /chat/completions 写进 base_url，工具会自动拼接
版本号漏写 — 有的服务需要 /v1 后缀，以文档为准
末尾斜杠 — 有的工具会拼成双斜杠导致 404，建议不加
model — 要什么
告诉 API "我要用哪个模型"。大小写敏感，必须和服务商文档一致。
正确写法
gpt-4o
deepseek-chat
claude-sonnet-4-20250514
anthropic/claude-sonnet-4
常见错误
GPT-4o（大写）
deepseek_chat（下划线）
claude-sonnet（缺版本号）
自编模型名（不存在）
二、「第二层参数」：三件套之外的配置
三件套解决的是"能不能用"。工具界面上还有供应商标识、供应商名称、温度、最大 token……这些是干什么的？哪些必须填？
供应商标识 vs 供应商名称
这两个经常搞混，但性质完全不同：
供应商标识（不能改）
技术层面的唯一编号
模型 ID 格式：标识/模型名
改了 → 所有引用失效
必须全局唯一
供应商名称（随便改）
纯 UI 展示标签
只在界面里显示
改了 → 不影响任何功能
随便起名
简单记：标识不能动，名称随便改。
官网地址和备注
这两个字段纯信息记录，不参与 API 调用。填不填都不影响使用。官网地址方便忘了是哪个服务商时点开看看，备注给自己看——比如"这个 key 是测试用的"或"额度快用完了"。
最大输入 token（context_window）
模型单次请求能接收的最大文本量。1 个中文字 ≈ 1.5-2 个 token。超了会直接报错。
▸ GPT-4o：128K tokens（约 10 万字）
▸ DeepSeek-Chat：128K tokens
▸ Claude Sonnet 4：200K tokens（约 15 万字）
▸ 便宜模型可能只有 4K 或 8K，容易踩坑
什么时候重要：传给模型的文本很长时（长论文、大代码库）。普通对话远达不到上限，不用管。
最大输出 token（max_tokens）
模型单次回复的最大长度。默认通常 4096 tokens（约 3000 字）。你要生成更长的内容，需要显式设置更大的值。
FIX不是越大越好
设得太大 → 模型可能"废话变多"
费用按 token 计费，输出越长越贵
温度（temperature）
控制输出的"随机程度"。范围 0-2。
● 0 — 最确定，同样输入永远同样输出。适合代码、数据提取。
● 0.7 — 常用默认值，平衡点。
● 1.0-1.5 — 更有创意但容易跑偏。适合写故事、头脑风暴。
● >1.5 — 基本在"发疯"，输出不可控。
不确定就用默认值，大部分场景够用。
top_p（核采样）
另一种控制随机性的方法。和 temperature 二选一，不要同时调两个。实操建议：只调 temperature，top_p 保持默认（1.0）。
频率惩罚 / 存在惩罚
● frequency_penalty（0-2）— 惩罚频繁出现的词，值越高越不容易重复
● presence_penalty（0-2）— 惩罚已提过的主题，值越高越容易切换话题
默认都是 0，大部分场景没问题。模型反复说同一句话时，提高 frequency_penalty 到 0.5-1.0。
参数重要性速查
● api_key / base_url / model / 供应商标识 — ✅ 必须填对，错了服务不通
● 最大输入/输出 token — ⚠️ 长文本时重要，普通对话不用管
● temperature / top_p / 频率惩罚 / 存在惩罚 — ❌ 可选，不确定就用默认值
● 供应商名称 / 官网地址 / 备注 — ❌ 纯展示，随便填不填都行
三、配置流程：五步走
▸ 第一步 — 注册服务商账号，拿到 API Key
▸ 第二步 — 去文档找 base_url，原样复制
▸ 第三步 — 看可用模型列表，记下准确名称
▸ 第四步 — 把三件套填到工具的配置界面
▸ 第五步 — 用 curl 或工具自带测试验证连通
四、连不上？四层排查法
第 1 层：网络通不通？
curl -I https://api.deepseek.com/v1/models
● 返回 200 或 401 → 网络通（401 只是没带 key）
● Could not resolve host → DNS 问题
● Connection refused → URL 写错了
● Connection timed out → 被墙或服务器宕了
第 2 层：Key 对不对？
curl https://api.deepseek.com/v1/models \ -H "Authorization: Bearer sk-your-key"
● 返回模型列表 → key 有效 ✅
● 401 → key 填错了
● 429 → key 没问题，请求太频繁
第 3 层：模型名对不对？
curl https://api.deepseek.com/v1/chat/completions \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek-chat",
"messages":[{"role":"user",
"content":"Hi"}]}'● 正常返回 → 全部配置正确 ✅
● 404 Model not found → model 名写错
● 400 Bad request → JSON 格式有问题
第 4 层：base_url 路径对不对？
FIX路径重复是最隐蔽的错误
base_url 写了 .../v1/chat/completions，工具又拼一次 → 404
正确做法：base_url 只写根地址，路径让工具自动拼
五、错误码速查
● 401 — 认证失败。key 填错、过期、或搞混了服务商
● 403 — 权限不足。key 有但没访问权，检查余额
● 404 — 找不到。model 名错或 base_url 路径不对
● 429 — 限流。等几秒再试，持续 429 检查余额
● 500/502/503 — 服务商挂了，等恢复
● SSL error — 常见于企业内网，需关 SSL 验证或导入证书
六、开发者必盯的五个细节
▸ base_url 末尾别加斜杠 — 有的工具会拼成双斜杠 → 404
▸ api_key 不要有空格和换行 — 从网页复制时最易带进不可见字符
▸ model 名严格按文档写 — gpt-4o 不是 gpt4o
▸ 区分平台 key 和模型 key — OpenRouter 一个 key 通吃，Azure 每个部署独立 key
▸ 注意 API 版本号 — /v1、/v2 不是装饰，以文档为准
铁律 不要凭感觉填，去服务商文档看原样。API 配置就三件事：你是谁、找谁、要什么。排查顺序：网络 → key → 模型 → URL。
SOURCES
OpenAI API Reference — developers.openai.com/api/reference/overview
DeepSeek API 文档 — api-docs.deepseek.com
Cline 文档：OpenAI Compatible — docs.cline.bot/provider-config/openai-compatible
LLM Parameters Guide — learnprompting.org/blog/llm-parameters
OpenClaw Provider 配置分析 — 本地文档
