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_ACCOUNTmain-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_ACCOUNTwork。如果你想自定义目录名也可以手动创建。接着还需要确认一件事项目目录里有没有.gitignore。如果没有建议马上加上一行.claude-code.env或者你自定义的配置名防止把账号信息提交进仓库。这个环节我多说一句不要只把 Key 当做唯一要保护的东西。项目 env 里如果写了ANTHROPIC_MODELclaude-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_KEYxxx终端里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 耗时相对 token 消耗重构嵌套回调30 分钟12 分钟较高修复随机测试失败20 分钟8 分钟中等写批量重命名脚本15 分钟5 分钟低结论其实很直接不要把 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 秒钟写下预算剩下的交给工具自动执行。