一把钥匙、三种协议、两个配置文件：AI API 小白指南

读完这篇你能做到什么

• 说清楚「API」到底是个什么东西，和你在网页上跟 AI 聊天有什么区别
• 在自己电脑上写出第一个调用 AI 的程序（Python / Node / 命令行三种都给）
• 看懂 OpenAI、Anthropic、Google 三家协议的差别，以及为什么「改一行就能换厂商」
• 手改 config.toml 和 settings.json，把 Codex、Claude Code 接到别家模型上
• 判断一个「中转站」值不值得用，以及它能看到你多少东西
• 明白 CC Switch 这类工具到底在你电脑上干了什么

全程不需要编程基础。看不懂的地方跳过就行，不影响照做。

一、先拆掉三个误解

新手卡住，八成不是因为难，而是因为一开始就理解错了。

误解 1：「API 就是网页版 AI 的另一个入口」

不是。它们是两个东西：

• 网页版 / App：一个做好的产品。有输入框、有历史记录、有登录、有会员。你按月付钱。
• API：一个给程序用的接口。没有界面，只有一个网址。你的程序发一段 JSON 过去，它回一段 JSON。按用量付钱，一个字一个字算钱。

打个比方：网页版是餐厅，服务员、桌椅、菜单都给你准备好了。API 是后厨的备餐窗口，你自己端着盘子来，说要什么，它给你什么——你得自己找地方吃。

为什么要用 API？ 因为只有 API 才能把 AI 装进你自己的东西里：你的网站、你的插件、你的自动化脚本、你的 Obsidian 笔记流程。网页版做不到这一点。

误解 2：「要先下载一个编译器，比如 VSCode」

这里有三个词被混在了一起，拆开：

VSCode 是编辑器，不是编译器。 而本文用的 Python 根本不需要编译器，它是解释器语言——你写完直接跑。

所以你要装的其实只有两样：VSCode（写代码的地方） 和 Python（跑代码的东西）。

误解 3：「API Key 就是密码」

比密码严重。密码泄露了，别人能登你的号；API Key 泄露了，别人能直接花你的钱，而且是自动化地、24 小时不停地花。

后面第五章会专门讲这个，那一章请务必看完。

二、一次 API 调用，到底发生了什么

拆开看就四步：

1. 你的程序把一段 JSON（里面是你要问的话）通过 HTTP 发到一个网址
2. 厂商的服务器收到，先验证你带的钥匙对不对，然后记一笔账
3. 把你的话交给大模型，模型算出答案
4. 服务器把答案打包成 JSON 发回来，你的程序解析出文字

你只需要凑齐三样东西，这三样就是所有 AI API 的最小公约数：

三、零基础环境搭建

3.1 装 VSCode

去 https://code.visualstudio.com 下载，双击安装。

Windows 用户装的时候注意勾上「添加到 PATH」。macOS 用户把它拖进「应用程序」文件夹就行。

打开后建议做两件事：

1. 左侧竖排图标最下面那个方块（扩展），搜 Chinese，装「简体中文语言包」，重启
2. 再搜 Python，装微软官方那个

3.2 装 Python

去 https://www.python.org/downloads/ 下载最新版。

macOS 系统自带 Python，但版本旧，建议还是装官网版。

3.3 验证装好了

打开终端（Windows 按 Win+R 输入 cmd；macOS 按 Command+空格 输入 终端），敲：

python3 --version

看到类似 Python 3.13.x 就成了。Windows 上如果 python3 不认，试试 python。

3.4 建一个练习文件夹

mkdir ~/ai-test
cd ~/ai-test

然后在 VSCode 里 文件 → 打开文件夹，选中这个 ai-test。

3.5 跑通第一个文件

在 VSCode 里新建一个文件叫 hello.py，写一行：

print("我能跑起来了")

保存，然后在 VSCode 顶部菜单 终端 → 新建终端，敲：

python3 hello.py

屏幕上出现那句话，环境就齐了。这一步跑不通就别往下走，后面全是在这个基础上加东西。

四、第一次调用 DeepSeek

选 DeepSeek 举例有三个原因：国内能直接注册充值、单价是同档里最便宜的、而且它用的就是「OpenAI 兼容协议」——一个例子能同时讲清「怎么调」和「什么叫兼容」。

4.1 拿 Key

1. 打开 https://platform.deepseek.com/ 注册
2. 进 https://platform.deepseek.com/api_keys 点「创建 API Key」
3. Key 只显示这一次，复制下来先存到记事本

充值入口在控制台里，具体支持哪些支付方式请自己打开看（这块我没法替你核实）。

4.2 当前的模型和价格

截至 2026-07-22，DeepSeek 在售两个模型（来源：官方定价页）：

两个都是 100 万 token 上下文，都支持「思考模式」（默认开启）。

「一百万 token」大概是多少？中文里 1 个 token 约等于 1 个汉字多一点。也就是说，用 flash 问一百万字的问题，花一块钱。这就是为什么值得自己接 API。

4.3 三种写法，同一件事

先把 Key 放进环境变量（不要写在代码里，理由见第五章）：

# macOS / Linux
export DEEPSEEK_API_KEY=sk-你的key

# Windows PowerShell
$env:DEEPSEEK_API_KEY="sk-你的key"

写法一：curl（什么都不用装，最能看清协议长什么样）

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
        "model": "deepseek-v4-pro",
        "messages": [
          {"role": "system", "content": "你是一个说话简洁的助手。"},
          {"role": "user", "content": "用一句话解释什么是 API"}
        ],
        "stream": false
      }'

这一坨就是「一次 API 调用」的全部真相。翻译成人话：

• -H "Authorization: Bearer xxx" —— 把钥匙别在请求头上
• "model" —— 点名用哪个模型
• "messages" —— 对话记录，system 是给 AI 的人设，user 是你说的话
• "stream": false —— 一次性把答案给我，不要一个字一个字蹦

写法二：Python（推荐新手用这个）

先装官方 SDK：

pip3 install openai

新建 ask.py：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("DEEPSEEK_API_KEY"),   # 从环境变量读，不硬写
    base_url="https://api.deepseek.com",          # 关键：换成 DeepSeek 的地址
)

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "你是一个说话简洁的助手。"},
        {"role": "user", "content": "用一句话解释什么是 API"},
    ],
    stream=False,
)

print(response.choices[0].message.content)

跑起来：

python3 ask.py

写法三：Node.js（想做网页或插件用这个）

npm install openai

新建 ask.mjs：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com",
});

const completion = await client.chat.completions.create({
  model: "deepseek-v4-pro",
  messages: [
    { role: "system", content: "你是一个说话简洁的助手。" },
    { role: "user", content: "用一句话解释什么是 API" },
  ],
});

console.log(completion.choices[0].message.content);

node ask.mjs

4.4 多轮对话怎么做

新手最常问的问题：「它怎么记不住我上一句说了什么？」

因为 API 本身没有记忆。 每次调用都是全新的一次，服务器不认识你。所谓「多轮对话」，是你自己把之前的对话全部再发一遍：

messages = [
    {"role": "system", "content": "你是一个说话简洁的助手。"},
    {"role": "user", "content": "我有两只猫"},
    {"role": "assistant", "content": "好的，记住了。"},   # ← AI 上一轮的回答，也要塞回去
    {"role": "user", "content": "我家一共几只脚？"},       # ← 这一轮的新问题
]

理解了这个，你就理解了为什么对话越长越贵——每一轮你都在为整段历史重新付一次钱。

五、API Key 的安全底线

这一章的每一条都有人真金白银栽过跟头。

5.1 三条硬规矩

1. 绝不把 Key 写进代码里。 用环境变量（上面那种 export 写法）或 .env 文件。
2. 绝不把 Key 传上 GitHub。 有专门的爬虫 7×24 小时扫 GitHub 上的新提交找 Key，泄露到被盗刷的时间通常以分钟计。如果用 .env 文件，必须同时建一个 .gitignore 写上 .env。
3. 绝不把 Key 贴进聊天窗口 / 截图 / 博客。 包括你为了问问题而截的那张图。

5.2 已经泄露了怎么办

立刻去控制台删掉那个 Key，再建一个新的。 不要犹豫、不要先查有没有被用——删除是唯一有效的止血手段，而且是免费的。

5.3 给自己上个保险

• 充值只充你输得起的额度，不要绑定自动续费
• 大多数平台能给单个 Key 设消费上限，建议设上
• 定期看一眼账单曲线，突然的尖峰就是信号

六、三大协议：它们到底差在哪

「协议」听起来很唬人，其实就是约定好的说话格式——像寄快递必须按固定格式填单子。目前主流有三家：

6.1 OpenAI 系（Chat Completions）

最早、也是事实上的行业标准。绝大多数第三方厂商（包括 DeepSeek）都选择兼容它。

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-5.6", "messages": [{"role": "user", "content": "Hello!"}]}'

6.2 Anthropic 系（Messages）

Claude 用的格式。和 OpenAI 有几处明显不同：

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "claude-sonnet-5",
        "max_tokens": 1024,
        "system": "你是一个说话简洁的助手。",
        "messages": [{"role": "user", "content": "Hello!"}]
      }'

四处差异，也是新手最容易翻车的地方：

1. 钥匙放在 x-api-key 头里，不是 Authorization: Bearer
2. 必须带 anthropic-version 这个头，不带直接报错
3. system 是顶层的独立字段，不能像 OpenAI 那样写成 messages 里的一个 role
4. max_tokens 是必填的，OpenAI 那边可以不填

6.3 Google 系（Gemini）

第三家，结构差得最远——它连「messages」这个词都不用。

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system_instruction": {"parts": [{"text": "你是一个说话简洁的助手。"}]},
    "contents": [{"parts": [{"text": "Hello!"}]}]
  }'

对话内容叫 contents，每条里面装的是 parts，鉴权头又换成了第三个名字 x-goog-api-key。

6.4 四个维度速查

鉴权头

• OpenAI：Authorization: Bearer <key>
• Anthropic：x-api-key: <key> + anthropic-version: 2023-06-01（两个都得有）
• Gemini：x-goog-api-key: <key>

系统提示词放哪

• OpenAI：messages 数组里 role: "system" 的一条
• Anthropic：顶层 system 字段
• Gemini：顶层 system_instruction

多轮对话

• OpenAI / Anthropic：无状态，每次把完整历史发回去
• Gemini 新版：可以用 previous_interaction_id 让服务端帮你串

流式返回（打字机效果）

• OpenAI："stream": true，一堆带 delta 的碎片，最后一条是 data: [DONE]
• Anthropic：具名事件 message_start / content_block_delta / message_stop，没有 [DONE]
• Gemini：URL 后面加 ?alt=sse

6.5 官方 SDK 对照表（2026-07-22 核实）

七、什么是「兼容」：为什么改一行就能换厂商

回到第四章那个奇怪的地方：我们装了 openai 这个包，却调通了 DeepSeek。

原理很简单：DeepSeek 在自己的服务器上，实现了一套和 OpenAI 一模一样的接口格式。

对 openai 这个库来说，它根本不知道自己在跟谁说话。它只负责：

1. 把你的参数打包成 OpenAI 格式的 JSON
2. 发到 base_url 指向的地址
3. 按 OpenAI 格式解析返回值

只要对方按同样的格式收发，它就通了。所以「换厂商」在代码上就是改 base_url + api_key + model 三行。

这就是为什么「OpenAI 兼容」几乎成了国内外所有 API 服务的标配——不兼容的话，用户迁移成本太高，没人愿意用。

反过来也成立

DeepSeek 同时还提供了一个 Anthropic 兼容端点：

https://api.deepseek.com/anthropic

意思是：你可以用 Anthropic 的 SDK、甚至直接用 Claude Code，去调 DeepSeek 的模型。这正是下一章「配置文件实战」的基础。

（细节：这个端点接受 x-api-key 头；anthropic-version 和 anthropic-beta 两个头会被忽略；如果你传了它不认识的模型名，会自动降级到 deepseek-v4-flash。来源：DeepSeek Anthropic API 文档）

八、中转站：便宜从哪来，代价是什么

8.1 它是什么

中转站（也叫 API 聚合平台、网关、relay）技术上做三件事：

1. 反向代理：你把 base_url 从官方地址改成它的地址，请求体一个字不改
2. 协议转换：把 Anthropic 格式 ↔ OpenAI 格式 ↔ Gemini 格式互相翻译
3. 计费：它自己发 Key 给你，自己记账

8.2 便宜从哪来——分清合规和灰色

8.3 几个能点名的平台（截至 2026-07 均可访问）

OpenRouter（https://openrouter.ai，国际，合规聚合）

• 实测聚合了 342 个模型、58 个厂商
• token 单价零加价，我逐条比对过 Claude 系列 12 个型号，与官方定价一分不差
• 钱收在充值环节：信用卡 5.5%（最低 $0.80/笔），加密货币 5%
• 隐私：默认只记 metadata，不记你的提示词和回复；可以选择开启记录换 1% 折扣
• 支持 Anthropic 原生格式，能直接接 Claude Code
• ⚠️ 但它自己声明：「Claude Code 只保证在 Anthropic 第一方 provider 上工作」

硅基流动 SiliconFlow（https://siliconflow.cn，国内）

• 严格说它不是中转站——上架的全是开源权重模型（GLM、DeepSeek、Qwen、Kimi 等），没有 Claude 和 GPT，属于自建推理服务
• 支持 Anthropic 协议，官方给了 Claude Code 接入文档

火山方舟 / 阿里云百炼 / 智谱开放平台

• 这三家是第一方官方平台，不是中转站，合同和计费直连厂商
• 三家都提供 Anthropic 兼容端点，都能接 Claude Code：
  • 智谱：https://open.bigmodel.cn/api/anthropic
  • 阿里百炼：https://dashscope.aliyuncs.com/apps/anthropic
• 具体套餐价格请自己打开官网确认——这几家价格页是动态渲染的，我核实不到准确数字，网上流传的数字互相矛盾，不敢写

自建开源网关

8.4 黑话解码

看中转站的宣传页，这些词你得认识：

• 官转 = 用官方 Key 转发（正规）
• 逆向 / 2API = 破解网页版或把包月订阅转成 API（违规）
• 满血 / 阉割 = 完整模型 / 被削过的
• 降智 = 表面点名大模型，背后偷偷换成便宜的小模型
• 上车 / 拼车 = 多人合租一个账号
• 翻车 = 服务挂了或跑路了

8.5 怎么自测一家中转站靠不靠谱

这几招都是可以自己动手验证的：

① 协议真实性探针

用一个无效的 Key 去打 POST {它的base_url}/v1/messages：

• 返回 401 → 这个路由真实存在，它确实实现了 Anthropic 协议
• 返回 404 → 它没实现，只是套了层壳

② 核对模型清单

GET {base_url}/v1/models，看返回的模型列表和宣传页对不对得上。

③ 价格反推

把它的单价和官方定价页逐条比。低于官方成本价的，必然有猫腻——没人做亏本买卖。

④ 上下文窗口探针

塞一篇长文档进去，让它总结中间某一段的内容。答不上来说明窗口被偷偷缩短了。

⑤ 小额起步

先充最小额度跑一周，别一次充几百上千。注册 2~3 家互为备份。

8.6 三个必须知道的代价

1. 你的对话内容对中转站是完全明文可见的。 别传公司机密、身份证、代码里的密钥。
2. 预充值有跑路风险。 OpenRouter 这种正规平台的退款政策都是「24 小时内、手续费不退、加密货币永不退」，无名小站更别指望。
3. 账单无法与官方对账。 Anthropic 官方的用量查询 API 需要 Admin Key、只覆盖你自己直连的组织——中转站不可能给你这个。这是「中转站账单查不清」的根本原因。

九、配置文件实战

前面讲的都是「自己写程序」。这一章讲怎么改配置文件，让现成的工具去连别家的模型。

9.1 Claude Code：settings.json

文件在哪

优先级从高到低：Managed（公司下发） > 命令行参数 > 本地级 > 项目级 > 用户级。

也就是说，项目级会覆盖用户级。想知道当前会话实际加载了哪几层，在 Claude Code 里敲 /status 看「Setting sources」那一行。

关键的三个环境变量

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的DeepSeek密钥",
    "ANTHROPIC_MODEL": "deepseek-v4-pro"
  }
}

改完重开 Claude Code 就生效了。

AUTH_TOKEN 和 API_KEY 到底选哪个？

这是最多人卡住的地方。区别只有一个——打进哪个 HTTP 头：

官方给的选择规则：

• 对方说「bearer token」或「Authorization 头」→ 用 ANTHROPIC_AUTH_TOKEN
• 对方说「API key」或「x-api-key」→ 用 ANTHROPIC_API_KEY
• 不知道 → 就用 ANTHROPIC_AUTH_TOKEN（官方原话）

这也解释了为什么国内中转教程清一色用 AUTH_TOKEN。

DeepSeek 官方给的完整配置（来源）：

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=<你的 DeepSeek API Key>
export ANTHROPIC_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-v4-flash

（[1m] 后缀表示 100 万上下文的变体）

官方建议的顺序：先在终端里 export 跑通验证，确认没问题再挪进 settings.json。

9.2 Codex：config.toml

文件在 ~/.codex/config.toml。格式是 TOML，比 JSON 好读一点。

⚠️ 这里有一个会让所有旧教程失效的变化

Codex 的 wire_api 字段，以前可以填 chat 或 responses。现在 chat 已经被彻底删除了。

三重证据：

1. OpenAI 官方公告（Discussion #7782）：2026 年 2 月完全移除
2. 当前源码里 WireApi 枚举只剩 Responses 一个值
3. 实测（codex-cli 0.138.0）报错原文：

Error loading config.toml: `wire_api = "chat"` is no longer supported.
How to fix: set `wire_api = "responses"` in your provider config.

注意是启动即报错、连开都开不了，不是「能跑但降级」。网上绝大多数「Codex 接 DeepSeek」教程现在都是废的。

字段含义

# ⚠️ TOML 规矩：顶层的键必须写在所有 [表] 之前，否则会被算进上一个表里
model = "deepseek-v4-pro"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"                        # UI 上显示的名字
base_url = "https://api.deepseek.com/v1" # 接口地址
env_key = "DEEPSEEK_API_KEY"             # ← 存 Key 的【环境变量名】，不是 Key 本身
wire_api = "responses"                   # ← 当前唯一合法值
requires_openai_auth = false             # false = 不弹 OpenAI 登录，直接用上面的 Key
supports_websockets = false

注意 env_key 这个设计很聪明：配置文件里存的是变量名，不是密钥本身，所以这个文件就算发给别人也不泄密。

其他常用字段：

十、CC Switch：它到底在你电脑上干了什么

看完上一章你应该已经明白了：所谓「换模型」，就是改那两个文件。

CC Switch 就是一个帮你改这两个文件的图形界面。 仅此而已——但这个「仅此而已」省掉了大量手抖改错 JSON 的痛苦。

10.1 基本信息（2026-07-22 核实）

• 仓库：https://github.com/farion1231/cc-switch
• 官网：ccswitch.io（README 特别声明这是唯一官网，说明有仿冒站，注意别下错）
• 12 万 Star，MIT 协议，Rust + Tauri 写的
• 最新版 v3.18.0（2026-07-21），大约一两周一个版本，非常活跃
• 支持 Claude Code、Claude Desktop、Codex、Gemini CLI 等 8 个工具，内置 50+ 服务商预设

10.2 安装

# macOS 推荐
brew install --cask cc-switch

Windows / Linux 去 Releases 页下载 .msi / .AppImage / .deb / .rpm。macOS 版本已做 Apple 签名和公证，双击就能开，不用绕 Gatekeeper。

10.3 原理：三句话讲完

1. 所有配置存在它自己的数据库里：~/.cc-switch/cc-switch.db（SQLite）
2. 你点「切换」时，它把对应那份配置写进真实文件：
   • Claude Code → ~/.claude/settings.json
   • Codex → ~/.codex/auth.json + ~/.codex/config.toml
3. 写入用「临时文件 + 改名」的原子操作，防止写到一半断电把配置写坏

反过来也成立：你手动改了当前激活的那份配置，它会反向读回数据库（官方叫 backfill），不会被你下次切换时覆盖掉。

10.4 生效时机

• Claude Code：支持热切换，不用重启
• 其他所有工具：要重启终端或重启 CLI

10.5 卸载了会怎样

不会怎样。它只是改文件，卸载后你的 CLI 工具照常工作，保持在最后一次切换的状态。也正因如此，它不允许你删除「当前正在激活」的那个 provider。

10.6 同类工具

十一、报错速查

十二、下一步

到这里你已经会了：调 API、看懂协议、改配置文件、评估中转站。接下来值得看的方向：

1. 流式输出：把 stream 改成 true，做出打字机效果——所有聊天界面都靠这个
2. Function Calling / 工具调用：让 AI 能调用你写的函数，这是所有「AI Agent」的地基
3. 提示词缓存：DeepSeek 缓存命中的价格是未命中的 1/50，长对话场景省钱效果惊人
4. 把它接进你已有的东西：Obsidian 插件、浏览器脚本、飞书机器人——你已经有全部前置知识了

附：本文的事实核实边界

以下内容截至 2026-07-22 已核对官方一手来源：DeepSeek 模型名与定价、三大协议请求结构与鉴权头、官方 SDK 包名、Codex wire_api 变更、Claude Code 环境变量语义与优先级、CC Switch 仓库状态与读写行为、OpenRouter 定价机制、开源网关活跃度。

以下内容未能核实，文中已回避或标注：DeepSeek 充值方式与发票、国内三家大厂 Coding Plan 的具体月费、DeepSeek 是否提供 Responses 端点、部分第三方中转站的运营主体与历史。

看到本文与你实际操作不一致时，以官方文档为准，欢迎在评论里指出。