Claude Code 命令行工具配置教程：自定义 API 节点与本地模型接入指南

内容总结生成中

你看见的，不仅是一个总结

Claude Code 的配置难点通常不在安装本身，而在于要把“终端环境、模型服务、项目配置”三件事分开处理。先保证命令行工具能正常启动，再决定请求是直连兼容 Anthropic Messages API 的服务，还是经由路由工具转发到本地 Ollama。这样排错时不会把网络、密钥和模型能力混在一起。

Claude Code 命令行工具配置教程：自定义 API 节点与本地模型接入指南

先准备终端环境与项目目录

安装前应确认本机具备可用的终端、Node.js 运行环境和包管理工具。部分相关工具要求 Node.js 18 或更高版本；如果终端中的 node、npm 与图形化开发工具使用的运行环境不同，后续很容易出现“命令存在但启动失败”的情况。

安装 Claude Code 后，建议先在一个普通项目目录中执行一次基础测试，确认命令能够运行。此阶段不要急着接入第三方服务，也不要同时修改多个配置文件。先建立一个最小可用环境，后面的异常才有明确归属。

Claude Code 的用户级配置通常位于用户目录下的 .claude 文件夹。其中，settings.json 适合保存长期生效的配置；而终端环境变量更适合临时切换模型、接口或密钥。

一个便于维护的配置结构可以是：

~/.claude/
├── settings.json
└── 其他本地配置文件

项目目录/
├── .git/
├── CLAUDE.md
└── 业务代码与文档

用户级配置放“连接方式和默认行为”，项目中的 CLAUDE.md 则更适合记录仓库约束，例如技术栈、测试方式、目录规则、禁止修改的文件范围等。不要把 API 密钥写进项目说明文件，更不要提交到 Git 仓库。

用环境变量接入自定义 API 节点

Claude Code 可通过 ANTHROPIC_BASE_URL 与 ANTHROPIC_AUTH_TOKEN 指向自定义服务。前提是该服务兼容 Anthropic Messages API 格式，并能正确处理相关版本与测试请求头。仅仅提供“聊天接口”的服务，未必能直接替代 Claude Code 所需的接口能力。

临时测试时，可以只在当前终端会话中设置变量：

export ANTHROPIC_BASE_URL="https://你的兼容接口地址"
export ANTHROPIC_AUTH_TOKEN="你的访问密钥"
export ANTHROPIC_MODEL="你的模型标识"

然后新开一个终端窗口，再运行 Claude Code 进行简单对话测试。若工具支持状态查看，可在会话中使用 /status，核对当前读取到的接口地址和认证令牌是否符合预期。

如果确认该节点会长期使用，可以将变量写入 ~/.claude/settings.json 的 env 字段。示例中的值应替换为你自己的服务信息：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://你的兼容接口地址",
    "ANTHROPIC_AUTH_TOKEN": "你的访问密钥",
    "ANTHROPIC_MODEL": "你的模型标识"
  }
}

这种方式比直接写入 shell 配置文件更集中，也便于按工具维度管理。但有一个常见误区：修改配置后仍在旧终端里测试。已经打开的终端未必会重新读取环境，因此遇到“明明改了配置却没有生效”时，先关闭当前会话并新开终端。

密钥不要直接硬编码在公开配置、项目脚本或共享文档中。团队协作时，更稳妥的做法是让每位开发者通过本机环境变量或私有密钥管理方式注入令牌，而不是共用一份包含真实凭据的配置文件。

本地 Ollama 模型需要路由转换

Ollama 提供的是 OpenAI 兼容接口，而 Claude Code 面向的是 Anthropic 风格请求。因此，Claude Code 通常不能仅靠修改一个地址就直接与 Ollama 通讯，需要增加一层能够完成协议转换的路由工具。

Claude Code Router 是一种可选方案：它可以接收 Claude Code 的请求，再按配置转换并转发到 Ollama 或其他模型服务。安装并启动后，路由工具会创建自己的配置文件。macOS 和 Linux 的常见位置是：

~/.claude-code-router/config.json

Windows 的常见位置则位于用户应用数据目录下的 Claude Code Router 配置路径中。

配置本地提供商时，核心信息不是“随便填一个模型名”，而是下面四项必须对应：

本地 Ollama 服务已经启动；
目标模型已经在本机拉取完成；
路由工具中的模型名与本地实际模型名一致；
路由协议选择能够把 Anthropic 请求转换为 OpenAI Chat Completions 的类型。

概念化配置如下，字段名称应以你所用路由工具的实际界面或配置格式为准：

{
  "provider": {
    "name": "Ollama",
    "base_url": "本地 Ollama 的 OpenAI 兼容接口地址",
    "protocol": "openai_chat_completions",
    "api_key": "ollama",
    "models": [
      "本机已下载的模型名称"
    ]
  }
}

本地服务没有启用鉴权时，某些路由工具仍可能要求填写非空 API Key。此时填入一个占位值即可；但这不代表公网部署时也可以忽略鉴权。只要本地模型接口暴露到局域网或公网，就应重新评估访问控制、反向代理和密钥保护。

另一个容易被忽略的问题是模型能力。Claude Code 不只是单轮问答，它可能需要理解长上下文、遵循复杂指令、生成补丁并配合工具调用。小型本地模型可以承担摘要、格式整理、简单脚本草拟等任务，但在跨文件修改、复杂调试和长任务规划上，效果可能明显不稳定。接入成功只说明“链路通了”，不等于“适合日常代理编程”。

配置文件要分层，而不是堆在一起

实际使用中，推荐把配置分为三个层次。

第一层是 shell 环境，适合临时实验。例如你想用同一台机器快速测试两个不同的 API 节点，可以在当前终端导出变量，完成测试后关闭终端即可恢复。

第二层是 Claude Code 用户级配置，适合长期默认值。例如默认接口、默认模型、上下文窗口设置等。它应当稳定、少改动，并避免保存会频繁失效的临时信息。

第三层是项目级说明，适合指导代理理解代码仓库。项目说明应聚焦“如何工作”，而不是“如何连接模型”。例如可以告诉 Claude Code：修改前先阅读现有测试、不要改动生成文件、接口变更必须同步文档、提交前执行项目既有检查。这类约束能减少多轮沟通，也降低代理误改的概率。

如果你经常在云端 API、本地 Ollama 和不同兼容节点之间切换，建议为每套配置保留独立的私有模板文件，再按需复制到生效位置。不要在一个文件里不断覆盖地址和模型名，否则很难判断当前会话实际走的是哪条链路。

用上下文缓存降低多轮编程任务的重复消耗

多轮编程任务里，成本往往不是来自某一句提示词，而是来自反复携带同一批仓库背景：项目规范、目录结构、接口约定、错误日志、已确认的方案。上下文缓存的价值，就是尽量避免每轮都重新处理这些稳定内容。

是否支持 Prompt Caching、缓存如何计费以及缓存命中条件，都取决于实际使用的模型服务或中转节点。不要假设第三方兼容接口一定完整支持这一能力。更稳妥的做法是先确认服务端文档或控制台能力，再调整工作流。

即使不研究底层缓存机制，也可以通过提示词组织方式提高复用机会。关键原则是：稳定信息放前面，变化任务放后面，并保持稳定部分尽量不变。

例如，在项目初始阶段先建立一份简洁的仓库说明：

项目目标：维护站点后台的内容发布流程。
技术约束：沿用现有目录结构与接口风格。
修改规则：先定位相关文件，再说明拟修改范围；未经确认不删除配置文件。
验证要求：修改后执行项目已有的检查，并说明未覆盖的风险。

后续每一轮只追加变化内容，例如“修复某个表单保存异常”“为某个接口补充校验”“根据最新错误日志分析原因”。不要每次都重新粘贴全部聊天历史，更不要在稳定约束中夹杂当天临时需求。前者会挤占上下文，后者会让缓存更难复用，也会增加模型误解旧指令的风险。

长任务还应当分阶段收束。完成“定位问题”后，让工具输出简短结论和待修改文件；完成“修改”后，再进入“测试与复核”。这样既能减少无关上下文持续累积，也能避免模型在很长的对话中继续依据已经失效的假设行动。

如果所接入的模型服务支持更大的上下文窗口，Claude Code 可以通过 CLAUDE_CODE_MAX_CONTEXT_TOKENS 设置相应上限，但前提是服务端模型确实支持该长度。盲目把窗口调大并不会自动提升结果，反而可能让无关日志、旧方案和重复指令长期滞留在上下文中。对于代码维护任务，清理上下文通常比单纯扩大窗口更有效。