free-claude-code：Claude Code免费额度管理实战

free-claude-code 是我最近整理的一个小工具，专门用来管理 Claude Code 的免费额度。很多人第一次听说 Claude Code 时，先被它那套命令行交互惊艳到，但真到自己上手，又容易被“额度到底还剩多少”“怎么在不同项目间切换不串 key”这种问题劝退。我的做法是写一组脚本，把额度检查、账号切换、项目隔离做成一条命令的事。这篇文章会把这组脚本的设计过程和踩坑经历完整拆开：为什么选 Shell、配置怎么组织、额度不足时怎么做，以及我实际使用三个任务的成本表现。如果你正准备低成本地把 Claude Code 接入到日常工作流，这篇可以直接拿来当参考。

1. 为什么我会想写一个“Claude Code 额度管家”

1.1 第一次被免费额度坑到的场景

事情发生在一次周末调试。当时我接了一个老项目的 bug 修复任务，代码横跨三个模块，牵一发动全身。我打开 Claude Code，熟练地粘贴报错信息，让它帮我梳理调用链。前十分钟一切顺利，AI 甚至给出了一个很漂亮的回溯分析。可就在这时，终端里突然弹出一条额度耗尽的提示，对话直接中断。我的第一反应是“换个账号再来”，但麻烦的是，我根本不记得刚才用的是哪个 Key，也不知道这个 Key 还有没有余额。翻配置、找文档、试环境变量，折腾了快四十分钟。

这段经历让我意识到一个问题：Claude Code 本身并不是难上手，真正难的是额度管理。免费额度和 API Key 是分散的，你可能有不止一个账号、不止一个项目，每个项目的上下文偏好还不一样。如果全靠人肉记，一两次还行，长期一定出问题。也就是从那天起，我决定写一个小工具，把“还剩多少”“当前用哪个”“下一个切到谁”这三件事自动化。

1.2 我理解的免费额度边界

先说明白：我这套工具不破解、不逆向、不碰任何付费墙。Claude Code 的“免费”来自官方公开的试用额度——新账号完成验证后会拿到一个有限的 token 包，按实际消耗扣除。这个额度通常会过期，也不能无限领取。free-claude-code 做的事情，只是把这些官方赠送的额度管理得更高效：启动前检查余额、切换账号、按项目隔离配置，避免因为操作失误把宝贵的额度浪费在错误的上下文里。

这话必须放在前面。因为我看到不少人在网上求“包永久免费”“无限 key”的脚本，这既不合规也不稳定。与其赌一个随时会失效的黑方案，不如把官方额度用明白。大多数开发者的痛点根本不是额度不够，而是没花在对的地方——比如反复让 AI 重新读同一个大目录，或者把个人聊天记录和历史项目都塞进上下文，token 消耗自然飞快。

1.3 三个目标：看得到、选得对、切得动

当时我给自己定下三个目标，也是 free-claude-code 的功能基线：

• 看得到：一句话输出所有账号的剩余额度，超过阈值的账号直接标红提醒。
• 选得对：进入某个项目目录后，工具能自动选择适合该项目的账号，不靠大脑记。
• 切得动：切换账号不用退出终端、不用重开终端，立即生效。

这三个目标听起来简单，但实现起来有一个隐藏难点：Claude Code 是一次性进程，它的配置在启动时就固定了。如果你在同一个终端里切 Key，除非重新启动 Claude Code，否则环境变量不会自动更新。所以“切得动”真正的意思是，脚本帮你写好配置文件，让下一次启动自动用新配置。听起来不复杂，但加上多账号、多项目、额度检查之后，就是一套完整的工程。而这套工程，就是 free-claude-code 的雏形。

2. 写这套脚本前，我先定下的几个设计原则

2.1 主流程用 Shell，解析用 jq

项目刚开始的时候，我在 Python 和 Shell 之间犹豫了很久。Python 处理 JSON、做逻辑判断都很顺手，但麻烦在于依赖：你需要保证目标机器上装了 Python 3 和相应库。而 Shell 基本所有类 Unix 环境都有，只要把解析任务交给 jq，复杂度就降下来了。

所以现在的实现是：主流程用 bash 写，所有 JSON 解析统一走 jq；余额查询如果需要计算，也先用 jq 出结果，再做条件判断。这么设计的好处是启动快、依赖少、调试直观。你跑bash -x ./fcc就能看到每一步干了什么，不需要 IDE 调试器。对于这种“命令行工具”性质的项目，可观测性非常重要。

下面是目录结构：

~/.free-claude-code/ ├── bin/ │ ├── fcc # 主命令 │ ├── fcc-ls # 查看余额 │ └── fcc-switch # 切换账号 ├── config.json # 全局配置：账号列表和阈值 ├── projects/ # 每个项目一个子目录 │ ├── blog/ │ │ └── env # 项目专用环境变量 │ └── cli-tool/ │ └── env └── logs/ └── fcc.log # 操作日志

不知道你有没有注意到，我没有把任何 Key 放在项目目录里。projects/blog/env只存“该用哪个账号别名”，不存 Key 本身。Key 全部集中在全局 config 中，并且设置成 600 权限。这样做的好处是，即使你随手把项目目录打成了压缩包发出去，也不会泄露凭证。这个设计是在一次真实的 Key 泄露事件后才补上的，后面我会细说。

2.2 配置按项目隔离，而不是全局一刀切

有朋友问过我：“我只有一个 Key，直接 export 到全局不就行了吗？搞这么复杂干嘛？”如果只有一个 Key、一个项目，确实没必要。但实际场景往往是：你同时维护两个项目，一个自己的学习项目，允许烧额度；一个是老板的正式项目，预算卡得很死。如果共用一套 Key，很容易互相污染。

我的做法是给每个项目独立的环境文件。文件里只有一行：

FCC_ACCOUNT=main-work

主命令fcc在进入项目目录后，会读这个文件，然后去全局 config 里找main-work对应的 Key，注入环境变量。这样，不同项目之间哪怕 Key 不同、模型不同、提示词前缀不同，也不会串。你可以在终端里来回 cd 到不同项目，每次启动 Claude Code 时用的都是正确的组合。

这里有一个容易被忽略的点：fcc use work生成的项目目录名默认取当前目录的 basename。如果你两个目录同名但内容完全不同，就会发生冲突。所以我在使用时会主动指定别名，比如fcc use work --as blog-backend，避免同名目录互相覆盖。这个坑我是在实际用了三天之后才发现的，早一点写进设计就能省掉一次痛苦的排查。

2.3 额度管理不是环境变量，而是资源池

把额度当成资源池来建模，是我觉得整个项目最值得说的一点。很多人对免费额度的理解是“设置一个 Key 就能一直用”，其实不是。额度是一个会在每个时间点变化的数字，你的任务每轮对话都可能在消耗它。所以脚本不能只在安装时检查一次，而要在合适的时机反复检查。

我实现了一个简单的余额缓存机制：每次查询后把结果写入~/.free-claude-code/balance.json，设置 5 分钟有效期。这样即使查询接口偶发失败，脚本也能读取上一次的记录，不至于直接罢工。另一个设计是“阈值预警”：比如你给某个项目设置"warning": 20，表示当剩余额度低于 20% 时，fcc会拒绝自动启动 Claude Code，除非你显式加--force。这种做法有点像是给预算上了个闸，防止你在无感知的情况下把额度耗尽。

这个“资源池”思路还体现在多账号调度上。如果config.json里有多个账号，且当前项目没有指定账号，我会让fcc自动选择一个“剩余额度最多且未过期”的账号。这种调度逻辑对个人场景特别实用，相当于手上攥着一把牌，哪张最厚打哪张。当然，如果某个账号是你专门留给重要项目的，我建议在项目 env 里显式指定，不要依赖自动分配，否则重要任务可能会用掉备用账号的额度。

3. 从零部署 free-claude-code：步骤拆解

3.1 下载工具并初始化目录

我习惯把这类工具放在用户目录下，而不是系统目录，方便随时改。初始化只需要三条命令：

mkdir -p ~/.free-claude-code/{bin,projects,logs} cp fcc fcc-ls fcc-switch ~/.free-claude-code/bin/ chmod +x ~/.free-claude-code/bin/* ln -s ~/.free-claude-code/bin/fcc /usr/local/bin/fcc

把fcc软链到/usr/local/bin后，就能在任何目录直接调用。如果你不想动系统目录，也可以把它加进~/.bashrc的 PATH。注意软链目标要在 PATH 里，且权限没问题。如果你用的是 zsh，记得检查~/.zshrc里有没有把/usr/local/bin排除掉，这个细节虽然小，但能让第一次使用少踩一次坑。

3.2 配置第一个账号

配置文件~/.free-claude-code/config.json的内容大概长这样：

{ "thresholds": { "warning": 20, "block": 10 }, "accounts": [ { "name": "main", "provider": "claude-code", "api_key": "sk-ant-xxxx", "note": "个人学习账号" }, { "name": "work", "provider": "claude-code", "api_key": "sk-ant-yyyy", "note": "项目专用" } ] }

写入之后立刻执行chmod 600 ~/.free-claude-code/config.json，把权限收窄。这是整个工具里最容易偷懒、但一旦偷懒就很容易出事的一步。如果你的系统里已经配置了 Claude Code 的全局环境变量，请记得在测试前先 unset，避免全局变量优先级盖过脚本注入的变量。我遇到过好几次“脚本明明改了 Key，跑起来却还是旧账号”的情况，最后发现都是全局变量在作祟。

3.3 为项目生成专属环境

进入项目目录，运行：

fcc use work

这条命令会读取当前目录名称，然后在projects/下生成一个对应目录，写入FCC_ACCOUNT=work。如果你想自定义目录名，也可以手动创建。接着还需要确认一件事：项目目录里有没有.gitignore。如果没有，建议马上加上一行.claude-code.env或者你自定义的配置名，防止把账号信息提交进仓库。

这个环节我多说一句：不要只把 Key 当做唯一要保护的东西。项目 env 里如果写了ANTHROPIC_MODEL=claude-3-5-sonnet或者某些组织内部使用的 prompt 前缀，同样是敏感信息。尽量让项目环境只保存“账号别名”和“模型别名”，其他敏感内容一律留在全局配置里。这样你即使把项目整个开源，也不会带出任何凭证或内部偏好。

3.4 日常两条命令：查看和切换

真正高频使用的主命令只有两条：

fcc ls # 查看所有账号余额 fcc switch work # 切换到 work 账号

fcc ls会调用官方接口（或者读取缓存）获取每个账号的余额，输出一张表：

NAME STATUS REMAIN THRESHOLD main ok 62% 20% work warning 18% 20%

当某个账号低于 warning 阈值时，脚本会直接退出，不启动 Claude Code，除非你用fcc use work --force。这个强制开关是我给自己留的一扇后门：如果只是处理一个 30 秒能搞定的问题，没必要专门去换账号。但我仍然建议平时不要用，毕竟强制启动之后，一旦忘了，可能直接把额度跑穿。

日常使用中我还有一个习惯：每天早上开工前先跑一次fcc ls，把它当作“今日预算”的晨检。看到表格里所有账号都是 ok，我就放心进入第一个任务；如果已经有 warning，我会先把最耗时的重构任务往后放，或者换成轻量任务。这样做了半个月，我再也没有出现过“任务做到一半发现额度没了”的尴尬。

4. 踩过的三个坑：排查过程比结论更值得看

4.1 坑一：Key 明明设置了，Claude Code 就是不认

这个坑我在项目调试到一半时遇到。我手动export ANTHROPIC_API_KEY=xxx，终端里echo $ANTHROPIC_API_KEY也能正常输出，但启动 Claude Code 后它依然提示没有凭证。一开始我以为是 Key 本身有问题，后来才意识到是环境变量名不匹配。

我的脚本里写的是ANTHROPIC_TOKEN，而 Claude Code 真正读取的是ANTHROPIC_API_KEY。这俩变量在很多文档场景下可以互相替换，但具体版本认哪个，必须实测。排查过程是：先用env | grep ANTHROPIC看当前环境，再对照官方文档确认变量名，最后在bash -x fcc里看到脚本注入的位置少了个_API。改完之后一切正常。以后再做类似工具，我会把环境变量名写成一个常量 map，放在文件最前面，方便集中检查。

这里有个延伸的教训：不要去猜环境变量的名字。哪怕你在网上看到一篇写得再像官方文档的帖子，也要以本地实际运行结果为准。最简单的验证方法是在启动 Claude Code 前用env | grep -i anthropic把当前环境打出来，确认变量名和值都对，再进交互。这个验证习惯帮我节省了大量无效排查时间。

4.2 坑二：余额查询接口超时，脚本直接假死

最开始版本里，fcc ls要逐个账号地请求余额接口。有时候某个账号的接口响应特别慢，脚本就会卡在那里，输出一直不刷新，很像假死。更糟糕的是，如果该接口返回 5xx，脚本没有重试逻辑，退出码是 1，而用户并不知道是接口问题还是工具问题。

我给这版做了三个改动：一是加了超时控制，用 curl 的--max-time 10，超过 10 秒就放弃本次查询；二是加了 5 分钟缓存，查询失败时返回上次结果并带一个(cached)标记；三是加了重试，第一个账号失败不阻塞后面账号，最终汇总时显示失败原因。改完后，fcc ls即便是遇到网络抖动，也能在几秒内给出可用结果。

这个坑值得展开讲的原因在于：很多小工具都是“自用即安”，出问题时只在自己电脑上能复现，换台机器就废了。多账号轮询是对稳定性的一个天然压力测试。如果你的工具需要调用远程接口，请从一开始就把超时、缓存、重试三件套做进去，这不是功能，而是基本生存保障。加了这三样之后，我的fcc ls才真正敢在演示场合用。

4.3 坑三：多项目并发，把同一份额度打穿

这是最让我肉疼的一个坑。有一天我开了两个终端，一个在重构旧模块，另一个在处理文档里的代码示例。两个项目配置里都指向了main账号，结果一个下午，免费额度就只剩个位数。不是任务本身多用，而是两个终端同时在跟 Claude Code 交互，每个对话都消耗一份上下文 token，加速效果几乎是乘法。

我没有去做复杂的并发控制，而是先加了一个简单的文件锁：fcc use work在切换时会检查~/.free-claude-code/.lock是否存在，如果存在就说明另一个进程正在使用这个 Key，脚本会提示你确认是否强制切换。这个方案很粗，但对单机个人使用场景已经够了。真正要彻底解决，还是得做到每个项目独立预算，这也是我后续计划要加的。

这里的核心教训是：免费额度不是“一个 Key 对应一个固定金额”那么简单，它更像一个共享水池。你开多少个终端，就相当于同时从水池里抽多少根管子。哪怕每个任务本身都很轻，并发起来消耗量也会快速累积。所以我在写工具时特意加了一个“活跃项目”检查，如果发现当前 Key 已经被另一个项目占用了，就至少让用户肉眼可见地确认一次，而不是默默被覆盖。

4.4 怎么看日志定位问题

配套的日志文件在~/.free-claude-code/logs/fcc.log，每次切换、查询、注入都会追加一行 JSON：

{"time":"2025-06-01T10:00:01Z","action":"switch","account":"work","result":"ok","detail":"cached"}

用tail -f实时看，配合jq .格式化，排查效率会高很多。很多人不愿意写日志，觉得工具小没必要，但等到出问题时你才发现，没有日志等于没有现场，一切只能靠猜。所以我从第一版开始就让所有操作都写日志，哪怕只是“切换账号失败”这种一行记录，也能帮你定位到是环境变量写错，还是配置文件权限不对。

日志不是写给用户看的，是写给出问题时候的你。每一条日志都应该包含时间、动作、账号、结果和附加信息。这样当你复制日志去提问或者自己复盘时，一眼就能看到完整的因果链。我的经验是：日志字段宁可多一个，也不要少一个；因为事后补日志，永远比不上事前写得全。

5. 实测效果：三个任务和一张开销表

5.1 任务一：重构一个嵌套回调

第一个测试任务是重构一段三层嵌套回调。原代码逻辑不复杂，但可读性很差。我直接告诉 Claude Code“把这段逻辑改成用 async/await 线性写法”，它给出了修改建议，我确认后让它直接改文件。整个流程大约用了 12 分钟，主要时间花在审阅改动上，而不是等回复。对比我之前手写重构，可能要 30 分钟以上。

这个任务之所以放在第一个，是因为它有典型的“上下文重”特征。代码文件本身不长，但调用关系散落在多个文件里，人工读一遍至少十几分钟。Claude Code 的优势就在这里：它可以一次性把相关函数都读进来，直接给出一份全局修改意见。而 free-claude-code 在这中间做的事，就是保证它启动时用的是正确的账号和项目配置，让我不用分心去管“这次对话是哪笔预算在烧”。

5.2 任务二：修一个测试失败

第二个任务是修复一个单元测试。测试用例里有一段超时断言，总是随机失败。Claude Code 先贴出了错误堆栈，然后建议用pytest-timeout代替手写超时。这个建议我当时其实是持怀疑态度的，结果跑了一轮测试，确实稳定通过。这个过程消耗的 token 不多，但避免了我在网上找半天的老问题。

这个任务让我意识到一件事：很多时候我们用 AI 改 bug，最大的成本不是 token，而是“你不敢让 AI 直接改测试文件”。因为有预算限制，我总是倾向于让 AI 先给方案，我来落代码。这样虽然慢一些，但能保证每一块改动都在我理解范围内。free-claude-code 的阈值预警在这里起了心理作用：知道额度还有多少，我才敢放心让 AI 多读几个文件。

5.3 任务三：生成批量脚本

第三个任务是让 Claude Code 写一个批量重命名脚本，把一批文件名里的日期格式从2025-01-01改成20250101。它直接在回答里生成了 Python 脚本，我复制到终端跑了一下，完全符合预期。值得注意的是，这类任务很“轻”，没有大量上下文，token 消耗特别低。所以如果你想体验 Claude Code，先拿这类小任务练手是最划算的。

这类轻任务的另一个特点是特别适合用来测试工具是否稳定。因为耗时短、消耗低，你可以在短时间内多跑几次，观察额度检查、切换、日志记录有没有异常。我就是在一次生成脚本的过程中，发现两个同名目录导致项目环境覆盖的 bug。轻任务因为快，反而更容易暴露流程上的小毛病。

5.4 这笔账算下来值不值

下面这张表是我在这三个任务上的实测开销，具体数值会因上下文和模型版本浮动，但比例可以参考：

结论其实很直接：不要把 Claude Code 当作自动代码生成机，而是把它当作一个“能快速定位问题、给出修改变更”的结对编程搭档。它最值钱的场景是那些你已经知道大致方向、但不想查文档和翻代码的任务。而 free-claude-code 的价值，就是让你在预算有限的情况下，把这种体验稳定地保留下来。省下来的时间不是让你多写代码，而是让你有工夫去思考更重要的事。

6. 后续想改进的地方，以及给后来者的经验

6.1 目前明显的短板

这个工具目前还有三个很明显的问题。第一，只支持类 Unix 系统，Windows 原生用户需要依赖 WSL，体验会打折。第二，余额查询依赖官方接口的稳定性，如果接口变了，我的 shim 层就得跟着改。第三，文件锁是单机锁，不支持团队多机共享同一个 Key 的场景，但团队场景本来也不建议共用 Key，所以影响有限。

我也在考虑加一个更细的“每项目预算”功能。比如每个项目设置一个独立的 token 上限，当该项目累计消耗达到上限后，fcc就拒绝在这个项目里启动 Claude Code。这能有效阻止“一个项目烧掉全部额度”的意外。实现思路不难，难的是如何准确获取单次会话的消耗数据，这个还得继续看官方 API 的返回字段。

另一个我想做但还没做的是“模型自动降级”。当额度剩余比例低于某个阈值时，自动把交互模型切换成更省 token 的版本。这个思路本质上跟限流一致：与其彻底停掉，不如用更便宜的方式继续跑低风险任务。但这里涉及到模型行为差异，不是简单换一个名字就能覆盖的，所以暂时只停留在规划阶段。

6.2 给想抄作业的人三条建议

如果你也想在自己环境里搭类似工具，我会建议三件事：

• 先保证能手动跑通，再自动化。我第一次自动化失败就是因为把 Key 名写错了，手动能跑通才算建立正确基线。
• 把账号信息做严格权限隔离。一个chmod 600和一个.gitignore能挡住九成低级泄漏。
• 日志从第一天就加。不要觉得“工具小不需要日志”，等到你半夜排查问题时，这句话会让你后悔。

最后再分享一个小技巧：在项目根目录放一个.fcc-budget文件，写上一个最大 token 数，然后在fcc主命令启动时解析它，超过就拒绝执行。我实际用下来，这个“预算断言”比任何提醒都有效，因为它从源头掐断了额度跑穿的可能。你只需要记得在开新项目时先花 10 秒钟写下预算，剩下的交给工具自动执行。