Claude Code 无限 API 使用指南

Claude Code 是 Anthropic 官方推出的命令行开发 agent，面向软件开发场景。它拥有 200k context window，可以创建拥有独立上下文的 subagents，会把读取过的完整文件写入对话历史，并且每一轮请求都会重新发送完整 context。随着会话变长，这种机制会带来接近二次方增长的 token 消耗，使 Claude Code 成为目前最“吃 token”的开发工具之一。把 Claude Code 接入 AI Prime Tech Unlimited 这种固定费率的 claude api中转网关后，它就不再是一个需要小心控制用量的工具，而可以真正变成全天候在线的开发伙伴，适合需要 claude无限使用 和 claude无限额度 的团队。

为什么 Claude Code 的 Token 消耗会呈二次方增长

从 API 的视角看，Claude Code 在每一轮请求之间是 stateless 的。也就是说，你发送的每条消息并不是只包含“本轮新增内容”，而是会携带完整的 conversation history：之前的所有消息、被读取过的文件内容、工具调用结果、assistant 的回复，以及任务过程中积累下来的各种上下文。第一条请求可能只有 5,000 tokens，看起来非常轻量；但到了第十轮交互，你可能已经在每次请求里发送 50,000 tokens 的历史，再加上本轮新加入的代码、日志或说明。到了第二十轮，一个复杂开发会话的单次请求 context 很容易超过 150,000 tokens。对于普通 chat 产品来说，用户往往只是在对话框里追加几句话；但 Claude Code 会不断读文件、执行命令、分析 diff、总结工具输出，因此 token 增长速度明显更快。

Subagents 会进一步放大这种消耗。当 Claude Code 把任务委托给 subagent 时，这个 subagent 会获得自己的 context window，并从一个相对干净的上下文开始独立积累历史。主 agent 的 context 会增加 subagent 返回的总结、结论和建议，而 subagent 自己也在持续产生新的 token 消耗。如果启用 agent teams，也就是多个 subagents 同时协作，消耗会继续被乘上活跃 agent 的数量。一个真实的大型任务可能同时包含一个 parent agent 和三个 subagents，每个 agent 都拥有 100k+ tokens 的上下文，并且都使用同一个 claude api密钥 发起请求。对于按 token 计费的 Anthropic 直连或普通 claude api中转，这种工作方式很容易让成本快速失控。

/compact 命令可以通过总结历史、截断旧 context 来缓解问题，但它本质上是一种人工干预：你用更短的摘要换取更多上下文空间，同时也牺牲了一部分细节。按 token 计费时，开发者经常会因为 claude api价格 压力而频繁 compact，甚至在模型还没有真正“忘记”之前就提前压缩上下文。接入无限额度后，使用方式会自然很多：你可以让对话按照开发节奏正常增长，只在 context 质量确实下降、模型开始抓不住重点时再 compact；也可以放心使用 subagents 和 background agents，而不用每次都在脑子里计算这一轮会花多少钱。对于经常长时间 pair programming、重构大型代码库、批量写测试的团队来说，claude无限使用 的价值就在这里。

环境变量配置

Claude Code 通过环境变量读取 API 配置。最关键的两个配置是 ANTHROPIC_BASE_URL，以及 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN 其中之一。使用 AI Prime Tech Unlimited 时，ANTHROPIC_BASE_URL 应设置为 https://claudeapikey.dev，也就是根域名，不要在末尾加 /v1，因为 Anthropic SDK 会自动拼接 API path。如果你把 /v1 写进 base URL，最终请求可能会变成 /v1/v1/messages，从而导致 404。API key 部分，如果网关使用标准 Anthropic 格式的 x-api-key header 认证，就设置 ANTHROPIC_API_KEY。对大多数用户来说，这也是最直观的方式：购买claude api 后，在后台拿到 claude api密钥，然后写入环境变量。

为了让配置长期生效，建议把这些变量写入 shell profile，比如 .bashrc、.zshrc，或者 Windows PowerShell 的 $PROFILE。Windows 用户也可以通过“高级系统设置”里的系统环境变量来配置。Claude Code 会在启动时读取这些变量，所以如果你修改了 ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY 或模型映射，最好重启当前 Claude Code session，让新值生效。很多连接问题并不是 API 不可用，而是旧 session 还在使用之前的 env var。配置完成后，可以通过 echo $ANTHROPIC_BASE_URL 或 PowerShell 的 $env:ANTHROPIC_BASE_URL 检查当前值。

如果你需要按项目区分配置，可以在项目根目录创建 .env 文件。Claude Code 会从当前 working directory 加载 .env，这样你就可以让不同项目使用不同 API 配置。例如，一个商业项目走 AI Prime Tech Unlimited 的 claude api中转，享受固定费率和 claude无限额度；另一个实验项目可能临时使用 Anthropic 官方直连，或者评估所谓 免费claude api 的可用性。.env 通常会覆盖系统级环境变量，因此很适合做 per-project overrides。不过要注意，包含 claude api密钥 的 .env 不应该提交到 git，建议加入 .gitignore，并在团队文档中说明每位开发者需要自行配置。

Sonnet、Opus、Haiku 和 Fable 的模型映射

Claude Code 内部使用模型别名，你可以通过环境变量覆盖这些别名对应的实际 model ID。ANTHROPIC_DEFAULT_SONNET_MODEL 控制默认选择 sonnet 时使用哪个模型；ANTHROPIC_DEFAULT_OPUS_MODEL 覆盖 opus 档位；ANTHROPIC_DEFAULT_HAIKU_MODEL 和 ANTHROPIC_DEFAULT_FABLE_MODEL 则控制其他模型层级。这里的值应该填写网关实际支持的精确 model ID，而不是你随手写的展示名称。不同 claude api中转 服务可能会使用不同命名方式，有的保留 Anthropic 原始 ID，有的会为了兼容不同客户端提供简化别名，因此需要以 AI Prime Tech dashboard 中显示的支持列表为准。

例如，你可以设置 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5，设置 ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6。之后当你在 Claude Code 里通过 /model 选择某个 tier，或者用启动参数指定模型时，Claude Code 会解析到你映射的实际模型。这对于两类场景特别有用：一类是网关暴露了自定义 model identifiers，你必须显式告诉 Claude Code 如何映射；另一类是你希望 pin 住某个具体模型版本，避免模型在后台升级后影响项目输出风格、代码偏好或测试生成方式。

在无限计划下，模型选择主要变成质量和速度之间的取舍，而不是成本问题。按 token 计费时，很多人会因为 claude api价格 选择更便宜的模型，只有关键任务才切到 Opus；但在固定费率方案里，不同 tier 之间没有单次调用成本差异。你可以把 Opus 作为默认模型，用来获得更强的代码理解、架构推理和复杂重构能力；只有在快速迭代、需要更低延迟时，再切到 Sonnet 或 Haiku。/effort 命令还能进一步控制 Claude Code 对任务的投入程度：如果你希望它更谨慎地分析代码库、更完整地评估边界条件，可以把高 effort 和 Opus 组合起来，这通常是 Claude Code 最强的工作模式。

Subagents、Agent Teams 和 Background Agents

Claude Code 可以创建 subagents，也就是拥有独立 context window 的 Claude 实例，用来处理被委派的子任务。当主 agent 遇到复杂任务时，它可以把调研、实现、验证、测试补全或代码审查交给不同 subagent。每个 subagent 都会从新的上下文开始工作，然后积累自己的 conversation history，最后把结果汇报给主 agent。这种机制非常适合大型代码库：主 agent 不必把所有细节都塞进同一个 context，而是可以让多个专门 agent 各自深入一个问题。

Agent teams 是对 subagents 思路的扩展，允许多个 subagents 同时围绕相关任务协作。主 agent 更像 coordinator，负责任务拆分、调度和结果整合。例如在一次大型迁移中，一个 subagent 可以负责重构 API client，另一个负责更新测试，第三个负责检查文档和类型定义。这样做效率很高，但 API 消耗会随着活跃 agent 数量线性增加，而且每个 agent 自己的 context 又会随着轮次增长。对于按量计费用户来说，这往往意味着必须谨慎限制 agent 数量；但对于购买claude api 并接入固定费率无限网关的团队来说，可以更接近真实工程协作方式地使用它。

Background agents 则可以在你继续使用主 session 的同时异步运行。它们处理独立任务，完成后再把结果返回。比如你在主会话里实现一个 feature，同时让 background agent 检查相关模块的测试覆盖率，或者让它扫描文档中需要同步更新的部分。按 token 计费时，同时跑多个 background agents 会很快变贵，开发者通常会犹豫要不要开；在 AI Prime Tech Unlimited 这类 claude无限额度 方案下，你可以让多个 background agents 并行处理项目不同侧面，再统一 review 输出，只要遵守 fair-use rate limits，整体都包含在固定费用中。

建议设置 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1，阻止 Claude Code 发送 telemetry 和非必要请求。对于任何自定义网关来说，这都是一个好习惯，可以减少噪声、降低排查难度，也避免把无关请求混入使用记录。另外，CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 可以让 Claude Code 向网关查询可用模型，而不是只依赖硬编码列表。对于经常更新模型、或者同时提供 Sonnet、Opus、Haiku、Fable 多档模型的 claude api中转 服务来说，开启模型发现能减少 model-not-found 这类配置错误。

Headless Mode 与 CI/CD 集成

Claude Code 的 headless mode 通过 --headless flag 启用，它不会进入交互式提示，而是适合 CI/CD pipeline、自动代码审查和批处理任务。在 headless mode 下，Claude Code 可以从 stdin 或命令行参数读取输入，把结果输出到 stdout，并在任务完成后退出，而不是继续等待下一轮输入。这种模式非常适合把 Claude Code 当作自动化工具嵌入开发流程，而不是只在本地终端里手动对话。

做 CI 集成时，你可以在 pipeline 配置中设置环境变量，例如 GitHub Actions secrets、GitLab CI variables 或 Jenkins credentials，然后把任务描述作为参数传给 claude --headless。常见用法包括自动 PR review、根据 diff 生成文档说明、为未覆盖模块批量生成测试、检查 migration scripts、总结 release 变更、扫描潜在 breaking changes 等。由于 claude api密钥 会出现在 CI secret 中，务必使用平台提供的加密变量，不要把 key 写进仓库。

在无限计划下，headless mode 的价值会被进一步放大。你可以让 Claude Code 针对仓库里的每个 PR 运行 review，为一批未测试模块生成测试套件，或者在每次 release 时自动更新文档和 changelog，而不用担心每次触发都会产生新的按量费用。传统按 token 计费下，团队往往只会在关键 PR 上使用这类自动化，因为 claude api价格 随调用量快速上升；固定费率的 AI Prime Tech Unlimited 则更适合高频自动化工作流。当然，“无限”并不意味着没有任何约束，仍然需要遵守 fair-use rate limits，避免无意义的循环调用或失控 pipeline。

CLAUDE.md 项目记忆与 Hooks

CLAUDE.md 文件用于提供持久化项目上下文，Claude Code 会自动加载它。你可以在项目根目录放置 CLAUDE.md，写入编码规范、架构决策、常见模式、命名约定、测试策略、部署注意事项以及项目特定指令。这些内容会被加入每次请求的 system prompt，因此会为每次调用增加 tokens，但也能显著提升回复质量和一致性。对于大型团队来说，CLAUDE.md 相当于给 Claude Code 的项目 onboarding 文档，让它每次进入仓库都能理解团队偏好。

如果是按 token 计费，很多用户会刻意把 CLAUDE.md 写得很短，因为文件中的每个词都会在整个 session 生命周期里反复增加 token 成本。结果是上下文不够充分，Claude Code 可能反复问同样问题，或者生成不符合团队规范的代码。接入 claude无限使用 后，策略可以完全不同：只要内容确实有助于模型理解项目，就可以写得更完整，例如详细架构说明、完整 style guide、依赖关系解释、模块边界、错误处理约定、API 设计偏好、测试命名规则等。额外 tokens 不会带来额外费用，而更好的上下文会在每一次交互中持续复利。

Hooks 允许你在 Claude Code 执行过程中的特定节点运行自定义脚本，比如 tool call 前后、session start、compact 时等。你可以用 hooks 注入动态上下文、把变更提交给本地 CI 校验、自动格式化代码、触发通知、检查安全规则，或者在模型写入文件前后执行额外检查。Hooks 运行在 CLI 层，而不是 API 层，因此和 AI Prime Tech Unlimited 网关可以无缝配合。对于希望把 Claude Code 变成工程自动化平台的团队，CLAUDE.md 提供静态项目记忆，hooks 提供动态执行逻辑，两者结合能显著提升 Claude Code 在真实开发流程中的稳定性。

Claude Code 网关问题排查

如果 Claude Code 无法连接，首先检查 ANTHROPIC_BASE_URL 是否设置为不带 /v1 的根域名。可以运行 echo $ANTHROPIC_BASE_URL，PowerShell 中则运行 $env:ANTHROPIC_BASE_URL，确认值是否为 https://claudeapikey.dev。Anthropic SDK 会自动追加 /v1/messages；如果你在 base URL 里写了 /v1，请求会变成 /v1/v1/messages，通常会返回 404。这是使用 claude api中转 时最常见、也最容易忽略的问题之一。

如果遇到 model-not-found 错误，通常说明模型映射变量里的 model ID 和网关实际提供的 ID 不一致。请到 AI Prime Tech dashboard 查看支持的精确模型标识，然后更新 ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL 或其他对应变量。注意 model ID 区分大小写，也可能包含版本后缀。很多用户在从 免费claude api 测试环境切换到正式无限额度网关时，会沿用旧的模型名称，从而导致 Claude Code 找不到模型。

如果主 session 正常，但 subagents 失败，问题可能在于 subagents 启动方式不同，导致它们继承环境变量的方式和主进程不一致。尤其在 Windows 上，如果变量只在当前 shell session 临时设置，子进程不一定能稳定继承。建议把 ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY 和模型映射写入系统级环境变量，或者确保启动 Claude Code 的 shell profile 已经正确加载。还可以临时在项目 .env 中显式声明配置，验证是不是环境继承导致的问题。排查时应优先确认 base URL、key、model ID、rate limit 和网络代理，再去怀疑 Claude Code 本身。

# Shell 环境变量（添加到 .bashrc / .zshrc / $PROFILE）
export ANTHROPIC_BASE_URL="https://claudeapikey.dev"
export ANTHROPIC_API_KEY="<your AI Prime Tech Unlimited key>"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# 或者使用项目级 .env 文件：
# ANTHROPIC_BASE_URL=https://claudeapikey.dev
# ANTHROPIC_API_KEY=sk-...
# ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5

# 运行 Claude Code：
# claude            （交互模式）
# claude --headless （CI/CD 模式）

FAQ

为什么 Claude Code 比普通 chat 消耗更多 tokens？
Claude Code 每一轮都会重新发送完整 conversation history，从 API 角度看它是 stateless 的。随着 session 变长，每次请求都会携带之前的消息、文件内容和工具结果，因此 token 会接近二次方增长。一个 session 中第 20 条消息的体积可能是第一条的 10 到 20 倍。

Subagents 会单独计算用量吗？
每个 subagent 都会运行自己的独立对话，并拥有自己的 context window。在 AI Prime Tech Unlimited 的无限计划中，parent agent、subagents、background agents 等 agent 对话都包含在固定费率内，不会按 agent 或 conversation 额外加价。

ANTHROPIC_BASE_URL 里需要包含 /v1 吗？
不需要。请设置为根域名 https://claudeapikey.dev。Anthropic SDK 会自动追加 /v1/messages。如果你在变量里手动加入 /v1，就可能形成重复路径并返回 404。

可以在 CI/CD 里用 Claude Code headless mode 搭配无限额度吗？
可以。把 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY 配到 pipeline secrets 中，然后使用 claude --headless 加任务参数运行。无限计划按同一固定费率覆盖 CI 使用，但仍需遵守 fair-use rate limits。

如何在 Claude Code 中切换模型？
可以在 session 中使用 /model 命令，也可以通过 ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL 等环境变量控制不同 tier 对应的模型。在无限计划中，模型之间没有按次调用的成本差异。