logo

Claude Code 安装与接入国产大模型完整教程

作者:有好多问题2026.11.17 03:17浏览量:1

简介:国内可以用,也能换成价格更低的国产模型——关键只有一件事:把 Claude Code 的 API 出口从 Anthropic 官方指向一个协议兼容的网关。如果你正在为"装不上""接不通""不知道选哪个模型"发愁,可以先看看[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article),它提供多模型统一 API 接入与价格、性能对比,能帮你先确定"接哪个模型最划算",再回到下面的步骤动手。

一、先搞清楚:Claude Code 到底是个什么东西

Claude Code 是 Anthropic 推出的 终端里的 AI 编程助手 。它和你熟悉的网页版聊天机器人最大的区别在于三点:

  1. 跑在你本机 :直接在终端(命令行)里运行,以你的项目目录为工作区。
  2. 有 hands :能读写文件、执行 shell 命令、跑测试、改 bug,而不只是给你贴一段代码。
  3. Agent 循环 :它会自己规划 → 改代码 → 跑命令 → 看报错 → 再改,直到任务完成。

你可以把它理解成一个”住在终端里的程序员搭档”。你说一句”给这个项目加一个 Spring Boot 登录接口,带 JWT 校验”,它会自己去建 Controller、写 Service、补依赖、跑编译。

但有个现实前提 :Claude Code 的客户端本身只是”壳”,真正干活的是它背后调用的大模型。官方默认连 Anthropic 的 API,国内直连不方便。所以本文的重点是: 装好壳 + 把壳接到一个你能稳定调用的模型上 。

好消息是,Claude Code 官方就留了口子——通过 ANTHROPIC_BASE_URL 等环境变量,可以把请求指向任意兼容 Anthropic Messages 协议的服务端点。这意味着国产模型只要提供了兼容接口,就能直接驱动 Claude Code。


二、第一步:装好”地基”

Claude Code 基于 Node.js 运行,所以先装 Node.js。

1. 安装 Node.js(要求 18 以上)

去官网 https://nodejs.org 下载, 选 LTS(长期支持版) ,不要选 Current——那个是给需要最新特性的开发者准备的,兼容性风险更高。下载后一路”下一步”。

验证:打开终端(Windows 按 Win+R 输入 cmd;macOS 按 Cmd+空格 输入 Terminal),执行:

  1. node -v
  2. # 输出类似 v20.15.0 即成功

如果版本低于 18,Claude Code 会在启动时直接报错退出,务必先升级。

2. Windows 用户额外装 Git

Claude Code 在 Windows 上依赖 Git Bash 执行部分命令。去 https://git-scm.com 下载,一路默认安装,然后验证:

  1. git --version

3. 建议:装一个包管理器(可选)

如果后续要频繁切换 Node 版本,用 nvm 会省很多事,但这属于进阶操作,小白可以先跳过。


三、第二步:安装 Claude Code

两种方式,效果完全一样,选一种即可。

方式一:npm 全局安装(跨平台通用)

  1. npm install -g @anthropic-ai/claude-code

如果遇到权限报错(常见于 macOS/Linux), 不要 直接用 sudo,推荐用 nvm 管理 Node 来规避;临时方案是修复 npm 全局目录权限。

方式二:官方原生安装脚本(推荐给不想碰 npm 的人)

macOS / Linux / WSL:

  1. curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

  1. irm https://claude.ai/install.ps1 | iex

这种方式不依赖 Node 版本,升级也独立,长期用更省心。

验证安装

  1. claude --version

能打印版本号就说明装好了。首次运行 claude 会进入交互界面,此时先别急着登录,我们直接去配模型。


四、第三步:接入大模型(三种方案)

这是全文最关键的部分。按你的实际情况选一条。

方案 A:官方 Anthropic 账号(需海外网络与支付方式)

直接运行 claude,走 /login 完成 OAuth 授权,或用 API Key:

  1. export ANTHROPIC_API_KEY="sk-ant-xxxx"

优点是模型能力与工具调用兼容性最好;缺点是接入门槛和成本对国内个人开发者偏高。

方案 B:Anthropic 协议兼容的第三方网关(推荐)

不少平台(包括国内云厂商的 AI 网关、以及各类聚合网关)会提供 Anthropic 兼容端点。配置只需两个变量:

  1. # macOS / Linux
  2. export ANTHROPIC_BASE_URL="https://你的网关地址"
  3. export ANTHROPIC_AUTH_TOKEN="你的密钥"
  1. # Windows PowerShell(临时生效)
  2. $env:ANTHROPIC_BASE_URL="https://你的网关地址"
  3. $env:ANTHROPIC_AUTH_TOKEN="你的密钥"

Windows 想永久生效:

  1. setx ANTHROPIC_BASE_URL "https://你的网关地址"
  2. setx ANTHROPIC_AUTH_TOKEN "你的密钥"

注意 setx 设置后要 重开终端 才生效。

判断一个网关能不能用,只看一条 :它是否实现了 POST /v1/messages 且支持流式返回与 tool_use(函数调用)。Claude Code 高度依赖工具调用,不支持 tool use 的端点即使能聊天,也没法真正改代码。

方案 C:OpenAI 兼容接口 + 协议转换层

如果你手上的模型只提供 OpenAI 格式的 /v1/chat/completions(这是国内平台最常见的情况),需要在中间加一层协议翻译。常见做法:

  • claude-code-router :专为 Claude Code 设计的路由工具,把 Anthropic 请求转成 OpenAI 格式,还能按场景(背景任务 / 主模型 / 长思考)分别指定不同模型。
  • LiteLLM Proxy / one-api :通用网关,自己起一个本地服务,再把 ANTHROPIC_BASE_URL 指向 http://localhost:4000。

以 claude-code-router 为例,思路是写一个配置文件,声明 Providers(各家模型的 baseURL 与 key)和 Router(默认模型、背景模型、长上下文模型分别用谁),然后启动路由服务,最后让 Claude Code 指向本地端口。

这种方案最大的价值是 混搭 :便宜的小模型跑文件摘要、命令解释这类轻任务,强模型只负责真正的架构设计和复杂改码,成本能压得很低。


五、把配置固化下来(别每次都 export)

每次开终端都敲环境变量太痛苦。Claude Code 支持在项目或用户级配置里写死:

~/.claude/settings.json(全局)或项目根目录 .claude/settings.json(仅当前项目):

  1. {
  2. "env": {
  3. "ANTHROPIC_BASE_URL": "https://你的网关地址",
  4. "ANTHROPIC_AUTH_TOKEN": "你的密钥",
  5. "ANTHROPIC_DEFAULT_SONNET_MODEL": "你选用的模型名",
  6. "ANTHROPIC_DEFAULT_HAIKU_MODEL": "轻量模型名"
  7. },
  8. "permissions": {
  9. "allow": ["Bash(npm run test:*)", "Bash(git status)"]
  10. }
  11. }

两点提醒:

  • 不要把带密钥的 settings.json 提交到 Git ,放进 .gitignore,或用系统环境变量代替。
  • ANTHROPIC_DEFAULT_*_MODEL 系列变量在不同版本中支持情况略有差异,若无效,用交互界面的 /model 命令手动指定即可。

六、验证与常见报错排查

进入 claude 后,用这些命令自查:

命令 作用
/status 查看当前接入的端点、模型、账号状态
/model 切换模型
/cost 查看本次会话的 token 消耗与费用
/doctor 环境自检,排查安装问题

高频报错对照表:

现象 大概率原因 处理
401 / 403 密钥错误,或该网关要求 ANTHROPIC_AUTH_TOKEN 而你设了 ANTHROPIC_API_KEY 换用正确的变量名
404 not found base URL 路径重复或缺失 有的网关要写到 /v1,有的不要,两种都试
model not found 模型名与网关侧命名不一致 用网关文档里的 原始 model id ,别自己猜
能对话但不会改文件 该模型不支持 tool use / 函数调用 换支持工具调用的模型
请求超时、频繁重连 网络链路或网关限流 检查代理设置,或换更近的接入点
长任务中途截断 上下文超限 用 /compact 压缩上下文,或换长上下文模型

七、模型选型与 Token 成本控制

Claude Code 是 极度消耗 token 的工具:它每轮都会把系统提示、工具定义、读过的文件内容一起发出去。所以选型不能只看单价。

计费的基本公式:

  1. 单次费用 = 输入 token/1M × 输入单价
  2. + 输出 token/1M × 输出单价
  3. + 缓存写入 token/1M × 缓存写单价
  4. + 缓存读取 token/1M × 缓存读取单价

Claude Code 默认开启 prompt caching,重复的系统提示和文件内容会命中缓存,缓存读取价格通常只有正常输入价的很小一部分—— 这是长会话成本能压下来的核心机制 ,但前提是网关要正确透传 cache 相关字段。

选型时建议按这几个维度权衡:

维度 说明
工具调用能力 一票否决项,不支持就不能用
长上下文 读大仓库、多文件重构时的刚需
输出单价 决定改码成本,Agent 场景输出占比高
缓存支持 直接影响长会话账单
稳定性与限流 频繁 429 会让 Agent 循环反复失败重试,反而更贵

具体哪家模型当前多少钱、能力如何,建议直接在词元所的大模型价格与性能对比上横向看一遍,再结合自己的任务类型定”主模型 + 轻量模型”的组合,比凭感觉选要靠谱得多。

三条立刻能省钱的习惯:

  1. 加 CLAUDE.md :在项目根目录写清技术栈、目录约定、构建命令、代码规范。Claude Code 会自动读取,能大幅减少它反复试探和读文件的开销。
  2. 收紧权限 :把 npm run test、git status 这类安全命令加进 allow 列表,减少每次确认打断 Agent 循环。
  3. 任务拆小 :与其一句”重构整个模块”,不如分几轮明确指令。上下文越干净,token 浪费越少。

八、上手建议

装好之后,别一上来就让它改核心业务代码。推荐这个路径:

  1. 在一个练手项目里跑 claude,让它读一遍代码并总结结构——观察它的 token 消耗速度。
  2. 让它做一个小改动(加个字段、补个单测),确认工具调用链路完全正常。
  3. 写好 CLAUDE.md,再逐步放开到真实项目。
  4. 需要接内部系统时,用 MCP(Model Context Protocol)扩展它的工具集,比如查数据库、调内部 API。

至此,从 Node.js 环境、Claude Code 安装,到三种接模型方案、配置固化、报错排查和成本控制,整条链路就通了。如果你还在纠结”接哪个模型”,可以先去百度智能云词元所完成模型发现、价格对比和统一 API 接入,把选型和接入这两步一次性解决,再回到终端里享受 Agent 编程的效率提升。

发表评论

活动