搭建一个面向志愿者、学生或社区用户的公益站时接入可用的 GPT 或 Claude 大模型并不是把模型名称写在页面上那么简单。实际使用中会涉及接口协议、密钥管理、调用参数、命令行工具安装、报错排查和安全边界而这些内容往往会消耗掉比功能开发更多的时间。这篇教程基于公益站接入 GPT 和 Claude 的常见场景从模型选型、环境准备、最小调用示例、Claude Code 安装到网关设计和排错清单梳理出一套可以直接落地的使用流程。无论是想为公众提供一个 AI 问答入口还是想让团队内部用 Claude Code 辅助开发或者只是希望从零跑通一个真实的大模型用例都可以按本文的顺序操作。先理解两家模型接口的差异再完成密钥和环境的准备之后用 Python 写出最小调用代码最后补齐生产环境需要的网关、限流和日志。1. 先理解 GPT 和 Claude 的接入方式差异1.1 同为大模型但接口协议并不通用GPT 是 OpenAI 提供的生成式对话模型Claude 是 Anthropic 提供的对话模型。两者都能完成文本生成、代码编写、摘要、问答等任务但在接口设计上有明显区别。OpenAI 的主流接口是 Chat Completions路径通常是/v1/chat/completionsClaude 使用的是 Messages API路径通常是/v1/messages。请求结构、鉴权方式、角色字段都不完全一样不能把一套请求直接改个 URL 就复用。OpenAI 的请求体核心是messages数组数组中每个元素包含role和contentrole可选system、user、assistant。Claude 的 Messages API 同样使用messages数组但system不是数组中的角色而是作为顶层参数传入。这是一个很常见的认知误区试图把 OpenAI 风格的system消息直接塞进 Claude 的messages数组会导致请求被拒绝或行为不符合预期。鉴权方式也不同。OpenAI 一般使用Authorization: Bearer API_KEYAnthropic 除了x-api-key头之外还要求传递anthropic-version请求头用来声明客户端使用的 API 版本。对于公益站这种需要长期维护的项目建议在网关层把两家接口的差异封装起来而不是在业务代码里散落处理逻辑。1.2 模型标识和调用能力先对齐模型标识是最容易写错的部分。以编写本文时常见的模型为例OpenAI 一侧常见标识有gpt-4o-mini、gpt-4o、gpt-4-turbo等Anthropic 一侧常见标识有claude-sonnet-4-20250514、claude-3-5-haiku-20241022、claude-opus-4-20250514等。模型列表会随官方发布更新每次升级 SDK 或对接新功能前都要以官方文档中的模型列表为准不要把老教程里的标识当作永久有效的值。公益站场景中选模型不能只看“哪个最聪明”。如果面向公众提供免费问答成本、响应速度、并发限制比单次回答质量更关键。需要写长代码任务时代码能力较强的 Claude 模型会更合适日常问答、摘要、分类等高频任务成本更低的轻量模型更实用。对比维度OpenAI GPT 系列Anthropic Claude 系列常见接口/v1/chat/completions/v1/messages鉴权方式Authorization: Bearerx-api-keyanthropic-version系统提示词放在messages数组的system角色中放在顶层system字段对话消息messages数组支持system/user/assistantmessages数组通常只使用user/assistantsystem是顶层参数适合场景通用问答、图像输入、插件生态长上下文、代码任务、复杂指令遵循1.3 公益站场景下应该选择哪种接入方式公益站的接入方式可以分成两种。第一种是站方统一申请 API Key在服务端完成调用用户只在前端页面输入问题。第二种是面向有开发能力的志愿者提供使用教程让他们在自己的环境里申请和调用。两种方式对教程的要求不同前者更关心网关、限流、成本控制后者更关心环境安装、命令行工具和 API 调用示例。本文会同时覆盖两条路径。前几章以站方视角为主逐步搭建最小调用和网关后面的 Claude Code 部分更多面向开发志愿者帮助他们把模型接入到本地开发流程。2. 环境和密钥准备这一步做错后面的报错会非常难查2.1 最小环境清单在学习环境里跑通示例不需要很复杂的组件。下面是常见的最小环境要求组件建议版本用途Python3.9 及以上运行 API 调用示例requests库最新稳定版发送 HTTP 请求Node.js18 及以上安装 Claude Codenpm随 Node.js 自带全局安装 CLI 工具Git可选克隆示例代码或做版本管理在命令行里依次确认环境版本python --version node -v npm -v如果在 Windows 上执行python提示找不到命令可能是没有勾选“将 Python 加入 PATH”需要重新安装 Python 并勾选该选项或者在系统环境变量中手动添加 Python 安装目录。这个坑虽然基础但在公益站的志愿者环境中经常出现。2.2 获取 API Key 的正确姿势获取 API Key 需要到 OpenAI 或 Anthropic 的官方开发者平台注册账号并创建密钥。创建完成时密钥通常只完整显示一次之后只能查看掩码或重新生成。实际项目中API Key 应当被视为和数据库密码同等重要的敏感信息。公益站如果由站方统一申请需要注意三点仔细阅读官方服务条款明确该模型是否允许通过第三方应用提供给公众。不要把自己的 Key 直接分享给普通用户也不要让 Key 出现在前端代码中。为 Key 设置预算提醒或硬性限额避免测试期间因请求异常产生高额费用。如果还没有 Key可以先在官方开发者控制台查看是否有免费试用额度。不同地区、不同账号的额度和计费方式可能不同落地前要以官方页面显示为准。2.3 用环境变量保护密钥而不是写死在代码里初学者最容易犯的错误是把 Key 直接写在 Python 文件里api_key sk-xxxxxxxxxxxxxxxx一旦代码被提交到公开仓库或者截图发到群聊密钥就泄露了。正确做法是把密钥放到环境变量或本地.env文件中并在代码里读取。在 Linux/macOS 的终端里可以临时导出export OPENAI_API_KEYsk-你的密钥 export ANTHROPIC_API_KEYsk-ant-你的密钥在 Windows PowerShell 里可以写成$env:OPENAI_API_KEYsk-你的密钥 $env:ANTHROPIC_API_KEYsk-ant-你的密钥Python 代码里不要直接写字符串而是从os.environ读取import os openai_key os.getenv(OPENAI_API_KEY) anthropic_key os.getenv(ANTHROPIC_API_KEY) if not openai_key or not anthropic_key: raise RuntimeError(请先设置 OPENAI_API_KEY 和 ANTHROPIC_API_KEY 环境变量)还可以创建.env文件然后使用python-dotenv加载from dotenv import load_dotenv load_dotenv()但要注意.env文件不能提交到 Git 仓库。使用 Git 管理项目时应该添加.gitignore并把.env写入其中。很多密钥泄露事件并不是黑客攻击造成的而是开发者不小心把配置文件提交到了公开仓库。注意API Key 泄露后要立即在开发者控制台吊销并重新生成不要试图在代码里继续补救。3. 用 Python 写两个最小调用示例3.1 调用 OpenAI 兼容接口这一节用一个最简单的 Python 脚本调通 GPT。使用requests库不依赖官方 SDK目的是让请求结构足够透明方便后续封装到自己的网关里。import os import requests api_key os.getenv(OPENAI_API_KEY) if not api_key: raise RuntimeError(请先设置 OPENAI_API_KEY 环境变量) url https://api.openai.com/v1/chat/completions headers { Authorization: fBearer {api_key}, Content-Type: application/json, } payload { model: gpt-4o-mini, messages: [ {role: system, content: 你是一个耐心的公益站学习助手。}, {role: user, content: 请用三句话解释什么是 API。}, ], temperature: 0.7, max_tokens: 300, } resp requests.post(url, headersheaders, jsonpayload, timeout30) data resp.json() if resp.status_code 200: print(data[choices][0][message][content]) else: print(f调用失败{resp.status_code}) print(data)关键点有三个headers里使用 Bearer Token这是 OpenAI 的标准鉴权方式。messages数组的顺序就是对话上下文顺序先 system 后 user后续如果继续对话需要把之前的历史消息全部带上。temperature控制随机性0 到 1 之间公益站问答场景一般取 0.3 到 0.7 之间太低会显得机械太高容易答非所问。3.2 调用 Anthropic Claude 的 Messages APIClaude 的请求结构不同需要把system放在顶层并在请求头里带上anthropic-version。import os import requests api_key os.getenv(ANTHROPIC_API_KEY) if not api_key: raise RuntimeError(请先设置 ANTHROPIC_API_KEY 环境变量) url https://api.anthropic.com/v1/messages headers { x-api-key: api_key, anthropic-version: 2023-06-01, Content-Type: application/json, } payload { model: claude-sonnet-4-20250514, system: 你是一个耐心的公益站学习助手回答尽量简洁。, messages: [ {role: user, content: 请用三句话解释什么是 API。}, ], max_tokens: 300, temperature: 0.7, } resp requests.post(url, headersheaders, jsonpayload, timeout30) data resp.json() if resp.status_code 200: print(data[content][0][text]) else: print(f调用失败{resp.status_code}) print(data)Claude 的返回结构和 OpenAI 不同content是一个列表列表元素根据类型不同可能包含text、tool_use等字段。最简单的文本输出通常取data[content][0][text]。写这段示例时尤其注意anthropic-version的值。这个值代表客户端声明的 API 版本不同版本可能在字段行为上有细微差别。如果没有特殊原因建议使用官方最新文档中推荐的值不要照抄旧示例。3.3 运行后应该看到什么结果将上面两个脚本保存为call_openai.py和call_claude.py设置好环境变量后执行python call_openai.py python call_claude.py正常结果会分别输出一句关于 API 的三句话解释。如果看到类似401 Unauthorized或authentication_error的响应优先检查环境变量是否设置成功以及 Key 是否粘贴完整。# Linux/macOS echo $OPENAI_API_KEY echo $ANTHROPIC_API_KEY # Windows PowerShell echo $env:OPENAI_API_KEY echo $env:ANTHROPIC_API_KEY如果 Key 已设置但仍然报 401到开发者控制台查看密钥状态确认是否已吊销或额度是否充足。3.4 参数调整和常见误区max_tokens在两种接口中含义一致都是限制生成的 token 数。不同模型对max_tokens的上限不同某些新模型对“最大输出 token 数”和“上下文 token 数”分别有独立限制调参前先查模型卡片而不是凭感觉填一个非常大的值。temperature不是所有模型都支持所有区间部分模型允许到 1 以上但公益站场景不建议开太高。生成结果不稳定会直接影响用户对站点的信任度。常见误区还包括请求超时时间设置太短导致网络稍有波动就失败忘记在循环对话中携带历史消息导致模型丢失上下文对返回体结构做硬编码索引遇到content列表为空时直接下标越界。这些都是生产代码中非常容易出现的边界问题。4. Claude Code 安装、配置与命令行使用4.1 Claude Code 解决什么问题Claude Code 是 Anthropic 提供的命令行编程代理工具可以在项目目录里读取代码、修改文件、执行命令把“让模型写代码”从聊天窗口搬到开发者本机。公益站的志愿者如果用它辅助开发可以先在本地跑通安装再把它接入到日常的代码维护中。它是 CLI 工具需要先安装再用命令行方式启动。不是浏览器里的聊天窗口这一点需要先区分开。4.2 安装前置条件安装 Claude Code 前本机需要准备好 Node.js 和 npm。常见版本要求是 Node.js 18 及以上可以使用以下命令确认node -v npm -v如果 Node.js 版本过低安装过程可能不会报错但运行时会出现兼容性问题。建议直接安装当前 LTS 版本不要使用过老版本。安装命令使用 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后验证版本claude --version如果能看到版本号说明安装成功。安装命令的具体包名和最新版本要以官方文档为准涉及升级时优先使用官方推荐的更新命令。4.3 Windows 下最常见的“claude 不是内部命令”错误在 Windows 的 PowerShell 或 CMD 中输入claude后出现下面这类提示是最常见的问题claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。 claude 不是内部或外部命令也不是可运行的程序或批处理文件。原因通常是 npm 的全局安装目录没有加入系统 PATH。npm 全局安装后的可执行文件并非总是自动加入 PATH尤其是通过 Node 官网安装 npm 时。先用下面命令查看全局安装目录npm config get prefix npm root -g如果npm config get prefix输出了类似C:\Users\你的用户名\AppData\Roaming\npm的路径检查这个路径是否包含在系统 PATH 中。如果不包含需要手动添加然后重新打开终端。打开系统设置 环境变量在“用户变量”的Path中新增上面的 npm 目录。修改完成后必须重新打开 PowerShell否则不会生效。另一个可能原因是 npm 安装失败。可以重新执行安装命令观察是否出现权限错误或无权限写入的提示。macOS 和 Linux 上如果使用系统级 Node可能需要在命令前加sudo但更推荐通过 nvm 安装 Node.js避免权限混乱。4.4 登录、配置和 VS Code 集成安装成功后在项目目录里执行claude首次运行会进入身份验证流程通常会在浏览器中打开授权页面按提示完成登录。具体登录方式要以工具当前版本为准不同版本可能支持 API Key 登录或账号登录。Claude Code 更适合在真实项目目录中运行因为它的价值在于读取项目文件、理解代码结构、修改代码而不是在空目录里闲聊。进入项目目录后用claude启动然后输入类似“帮我看看这个目录的代码结构”或“修复 README 里的错别字”这样的指令。VS Code 用户不需要额外做太多配置打开终端并在项目目录下运行即可。如果安装了官方推荐的 Claude Code 扩展可以直接在编辑器界面里看到会话面板具体扩展名称和安装方式以官方市场页面为准。Claude Code 中还有一个概念叫 Skills可以理解为让模型按既定流程执行某些任务的额外能力。比如为项目定义一个“写提交信息”的 Skill让模型每次运行固定工具生成规范提交内容。具体如何创建和挂载 Skills不同版本差异较大使用前先查看对应版本文档。注意不要在一个包含大量私密配置文件的目录里直接让 Claude Code 执行高风险命令。先确认工具对本地命令的执行权限再决定哪些目录可以使用。5. 公益站接入大模型的前后端设计5.1 为什么不能让浏览器直接调大模型接口很多初学公益站开发的人会想既然 API 调用这么简单为什么不直接在前端页面里调用原因是这样会把 API Key 暴露给每一个访问者任何人都能从浏览器开发者工具里看到密钥然后用这个 Key 消耗你的额度。此外直接前端调用还会带来三个问题无法限制单个用户的调用频率无法对请求内容做安全过滤也无法统计公益站到底被哪些功能消耗了多少成本。正确的做法是在服务端套一层网关由公益站后端持有密钥前端只能请求后端接口。5.2 一个最小后端转发示例下面用 FastAPI 写一个简单的网关思路只保留核心转发逻辑。实际项目中还需要补充鉴权、限流、日志和异常处理。from fastapi import FastAPI, HTTPException from pydantic import BaseModel import os import requests app FastAPI() OPENAI_API_KEY os.getenv(OPENAI_API_KEY) ANTHROPIC_API_KEY os.getenv(ANTHROPIC_API_KEY) class ChatRequest(BaseModel): provider: str # openai 或 anthropic model: str messages: list system: str temperature: float 0.7 max_tokens: int 300 app.post(/api/chat) def chat(req: ChatRequest): if req.provider openai: payload { model: req.model, messages: [ {role: system, content: req.system}, *req.messages, ], temperature: req.temperature, max_tokens: req.max_tokens, } headers { Authorization: fBearer {OPENAI_API_KEY}, Content-Type: application/json, } resp requests.post( https://api.openai.com/v1/chat/completions, headersheaders, jsonpayload, timeout60, ) if resp.status_code ! 200: raise HTTPException(status_coderesp.status_code, detailresp.json()) return {role: assistant, content: resp.json()[choices][0][message][content]} if req.provider anthropic: payload { model: req.model, system: req.system, messages: req.messages, temperature: req.temperature, max_tokens: req.max_tokens, } headers { x-api-key: ANTHROPIC_API_KEY, anthropic-version: 2023-06-01, Content-Type: application/json, } resp requests.post( https://api.anthropic.com/v1/messages, headersheaders, jsonpayload, timeout60, ) if resp.status_code ! 200: raise HTTPException(status_coderesp.status_code, detailresp.json()) return {role: assistant, content: resp.json()[content][0][text]} raise HTTPException(status_code400, detail不支持的 provider)代码里要特别注意messages中不应包含system角色因为 OpenAI 和 Anthropic 对系统提示词的处理方式不同统一由后端把系统提示词放到对应位置能减少前端传入脏数据的风险。公益站前端只负责把用户消息传上来即可。5.3 用量控制、日志和内容安全网关只解决密钥安全不能解决费用失控。公益站是低成本运营场景更需要控制用量为每个匿名用户生成会话 ID限制每分钟请求次数。为每个用户设置每日请求上限超限后返回明确的提示文案。对高频用户做熔断避免某个用户拖垮整个站点的 API 额度。记录每次请求的模型、token 消耗、响应耗时但不记录完整的敏感用户输入或只保留脱敏后的一段摘要。内容安全方面系统提示词中要明确模型的回答边界对输入做长度限制防止超长文本占用过多 token对输出进行基础过滤避免生成明显违规内容。更复杂的审核需要引入额外服务公益站初期可以先从提示词和长度限制做起。注意如果公益站面向未成年人需要在产品层面增加年龄相关提示并避免诱导生成不当内容。不同平台对未成年人使用生成式 AI 有不同要求上线前要按所在地区的规则评估。6. 高频报错排查从现象到根因下面的表格汇总了 GPT 和 Claude 接入过程中最常出现的几类问题。排查顺序建议先确认密钥再确认网络再确认版本最后分析代码逻辑。问题现象常见原因检查方式处理建议claude不是内部或外部命令npm 全局目录未加入 PATHnpm config get prefix查看 PATH将 npm 全局目录加入用户 PATH重开终端401 Unauthorized或authentication_errorAPI Key 错误、过期或已吊销echo $OPENAI_API_KEY控制台查看密钥状态重新生成 Key更新环境变量429 Too Many Requests请求频率过高或余额不足查看开发者控制台用量降低频率增加预算或使用轻量模型model not found模型标识写错或账号无权限对照官方模型列表检查换成正确的模型标识context length exceeded上下文超过模型限制查看错误中的 token 数量减少历史消息对超长文本做摘要content下标越界返回体中没有text字段打印完整响应 JSON先判断content[0].type再取值浏览器跨域报错前端直接调用 API查看 Network 面板改为后端转发并配置 CORS 白名单模型回答与设置的系统提示词无关system 位置错误对比两家接口的请求体OpenAI 放messages[0]Anthropic 放顶层system排查链路可以按这样的顺序来确认环境变量是否真的存在不要只检查代码里是否写了。确认请求是否到达正确的接口用print或日志打印 URL 和状态码。确认模型标识是否可以通过官方模型列表验证。确认返回体结构不要凭记忆取字段。确认日志中是否有明确的异常信息再决定是否需要查看网络层。关于 GPT 或 ChatGPT 的归档功能很多用户会问“归档的对话去哪里了”。在 ChatGPT 应用中归档不会删除会话只是把会话从默认列表移动到归档列表。可以在侧边栏或设置入口找到归档列表把对话移出归档即可恢复显示。这与 API 调用无关但很容易被误认为数据丢失。7. 学习环境与生产环境的差异公益站接入大模型最关键的是分清学习和生产边界。下面的表格可以帮助判断当前处于哪个阶段。维度学习环境公益站生产环境API Key本机环境变量服务端配置中心或安全存储请求方式脚本直接调用后端网关转发密钥暴露仅限本机前端不可见日志可完整打印响应脱敏、不记录敏感输入限流不需要必须有预算关注单次调用设置每日总预算和告警模型选择测试用默认模型按成本和效果做路由回滚改代码重启配置开关、灰度发布生产环境至少还需要做到配置外置化。API Key 不要写在 Dockerfile、镜像或代码仓库里建议使用环境变量注入或密钥管理服务。启动服务时没有检测到必要环境变量应当直接失败而不是等用户请求时才报 500。日志和监控是公益站长期稳定运行的基础。每一条请求都应该记录调用方会话 ID、使用的模型、上下文字数、响应耗时、返回状态。一旦出现费用异常或响应变慢能快速定位到是哪个功能、哪个时间窗口、哪个模型导致的。还有一点容易被忽视提示词注入。当用户输入被拼接进系统提示词时用户可能利用恶意输入让模型忽略原有指令。公益站允许公众匿名访问这一风险更高。缓解方式是不要把系统提示词完全暴露给用户对用户输入中的指令性内容保持警惕同时不要让模型把 API Key、内部规则等敏感信息写入输出。不要试图在系统提示词中放置机密信息因为它可能通过提示词注入被诱导输出。8. 可复用检查清单与下一步扩展方向8.1 公益站 API 上线前检查清单按这个清单过一遍能减少大多数低级问题环境变量是否在服务端正确配置且未提交到代码仓库。前端页面是否完全不包含 API Key 或上游接口地址。后端是否实现每分钟请求次数限制和每日请求上限。日志中是否包含请求耗时、状态码、token 数且不包含完整敏感内容。是否设置了预算告警预算超限时能否自动熔断。是否处理了流式传输或超时场景防止用户长时间等待。是否对输入长度做了校验避免超大请求耗尽上下文。模型标识是否来自官方模型列表而不是从旧代码里复制。是否有明确的错误提示文案而不是直接把 JSON 错误抛给用户。是否在测试环境验证过 OpenAI 和 Claude 两条调用链路。8.2 本地调试清单如果遇到“我第一次调用就报错”的情况按下面的顺序排查python --version和node -v确认基础环境。环境变量是否在当前终端会话中生效。单独运行最小调用脚本确认 API 连通。打印完整的响应 JSON确认结构。查看开发者控制台中的用量和错误记录。检查代码中是否有文件路径、目录名或包名拼写错误。8.3 下一步扩展方向跑通 API 调用之后公益站可以在不同方向上进一步扩展。本地部署小模型。如果公益站面向的是离线或低成本场景可以考虑用 Ollama、vLLM 等方式在自有服务器部署轻量开放模型减少对云端 API 的依赖。本地部署仍有许多工程问题包括显存、并发、模型量化不能简单等同于“下载一个模型就能用”。微调垂直领域模型。如果用户习惯提问某一类专业问题可以在通用模型基础上使用 LoRA、QLoRA 等方式做领域微调。微调需要准备高质量数据集数据质量比数据量更关键。多模态与代码代理。除了文本问答GPT 和 Claude 相关生态还提供图像理解、图像生成、代码代理等能力。引入这些能力前先评估公益站是否有对应场景否则会显著抬高成本和维护复杂度。安全性评测。公益站面向公众建议定期做提示词注入测试和内容安全抽查发现模型被诱导输出不合适内容时及时调整系统提示词和过滤规则。服务编排。当单次请求需要同时使用文本模型和检索能力时可以引入 RAG 架构让模型先检索资料再基于资料回答。这里要注意检索结果的分块、去重和引用来源问题。大模型接入对公益站的意义不在于把模型名称写成功能列表而在于让有限的技术团队用可维护的方式把 AI 能力交给最终用户。先跑通最小调用再补齐密钥管理、网关、限流和日志最后根据实际使用数据优化模型选择和成本这是比较稳妥的落地顺序。对新手来说最有价值的练习不是一次接入所有模型而是反复重写一遍调用脚本直到自己能够不查资料就说出请求结构、鉴权方式和返回体字段的区别。