free-claude-code：开源脚本+免费模型接口搭建命令行AI助手

说实话我一开始对 free-claude-code 这个词是持怀疑态度的。市面上的 AI 编程助手一个比一个贵订阅制按年砍一刀偶尔给点免费额度又藏着各种限制。但这半年我把自己的日常编码流程全部换了一遍用一套完全免费、自己可掌控的方案把终端里的代码解释、自动审查、提交信息生成做成了顺手的工作流。它不是某个现成的商业产品是我给这套方案起的工程代号。全程只用了开源脚本加一个免费模型接口没有花一分钱订阅费。这里说的 free-claude-code不涉及去绕过谁的付费墙而是一个完全合规的 DIY 方向用免费大模型接口和开源脚本组合出类似能力。名字里的 claude-code我更多把它当作一种“代码助手”的代称代表终端里那个能看代码、能回答、能帮你把关的“副驾驶”。你完全可以把这套思路复制到任何模型上核心逻辑不变。1. free-claude-code 是什么先拆清楚要解决的问题1.1 商业 AI 编程助手贵在哪先不讨价还价我们先看那些收费工具到底在卖什么。商业 AI 编程助手能做的事情本质上是三件事理解你当前的代码库、把自然语言指令转成代码操作、以及在你写码过程中实时反馈。这三件事背后是巨大的工程投入。模型本身要持续训练和推理尤其是为了保持“实时补全”的低延迟服务商需要在全国甚至全球部署加速节点。再加上上下文窗口越来越大一次请求可能要处理几十万个 token这部分算力成本并不低。所以你付的年费里一半是模型能力另一半是“快”和“方便”。问题在于并不是所有人、所有场景都需要这种“快和方便”。我自己的日常并不是每分钟都在敲代码。更多时候是在读旧代码、改前人留下的逻辑、写提交说明、查某个变量的作用域。这些场景对延迟不敏感对模型能力要求也不极端完全可以走更经济的路由。这就是 free-claude-code 存在的理由把需求拆开只留那些真正必要的环节其余全部剪掉。1.2 免费方案的设计思路free-claude-code 的核心思路是一句话模型能力和工程外壳分开。模型能力是用来“理解语言和代码”的部分它可以来自本地部署的小模型也可以来自某个免费额度的云端接口。工程外壳则是你自己写的 Python 脚本、Git 钩子、正则表达式它负责“看代码、组织上下文、发起请求、整理结果”。这两个层边界非常清晰。想换模型只改配置想换任务类型只改外壳。不需要一个庞大的 IDE 插件也不需要把工具绑死在某个平台上。我只需要一条命令告诉我当前目录里有什么文件我要它做什么它就能自己去调用模型给出结构化答案。这个设计带来的最大好处是自动化可以随便接。GUI 助手再方便也很难帮你跑在每个 git commit 之前。但我写的壳脚本可以因为它就是一个命令行程序。1.3 谁适合用 free-claude-code不是所有人都需要这套东西但下面三类人会很受益。第一类独立开发者和小团队。项目规模不大订阅一整年的商业助手利用率不高自己拼一套反而更灵活。第二类编程学习者。你想让自己保持“手写代码”的手感同时希望有一双随时帮你指出问题的眼睛。用命令行工具来辅助而不是让 IDE 自动补全替你完成一切学习效果会好很多。第三类对代码隐私比较敏感的人。尤其在一些内容还没公开的模块里不想把每一行都传到第三方服务器。用本地模型做默认路由敏感代码不出机器这是商业订阅很难给到的确定性。反过来如果你需要严格的权限审计、团队共享、7×24 小时 SLA 保障那还是老老实实用商业化托管服务自建方案不适合你。2. 选型思路与关键判断2.1 本地部署模型和云端免费额度怎么选这是自由方案里最核心的岔路口。我两种方式都跑过给一个比较实在的对照。维度本地模型云端免费额度运行环境自己的电脑或旧服务器第三方接口无需维护硬件数据隐私离线运行不出本机数据会经过服务端硬件要求内存 8G 起步建议 16G无额外要求单次响应速度取决于内存和 CPU/GPU通常偏慢一般较快但可能有频控长上下文能力受限于显存或内存一般更充裕稳定度本地自己控制受制于服务商策略我自己现在的做法是“本地优先云上兜底”。简单任务比如“这个函数有没有明显的空指针风险”“给这段代码写一个 commit message”直接用本地小模型几秒钟出结果不心疼资源。复杂任务比如“帮我分析这个模块里所有跨文件的状态变更路径”本地小模型容易掉链子我会走云端免费额度。不要试图只依赖一头的资源。只依赖本地遇到难问题会卡壳只依赖云端免费额度一旦触发限流整个工作流就断在中间。双路由是容错性最好的组合。2.2 外壳脚本是自己写还是用现成的市面有不少现成的命令行 AI 工具能直接对接各种模型服务。它们的好处是开箱即用配置一个 API Key 就能跑。但弱点在于它们面向通用场景不理解你的项目结构也不了解你的代码规范。你想让它只检查你规定目录下的 Python 文件或者让它把警告写成特定格式改起来反而比从头写还费劲。所以我建议先用现成工具跑通一次感受一下请求和响应的结构然后马上尝试自己写一个最小外壳。这个外壳可能不到一百行但你能完全控制它做什么。我的第一个 free-claude-code 脚本特别简陋就是接收两个参数文件路径和问题描述。脚本把文件读进来拼接成一段提示词调用模型接口把返回结果打印在终端里。但就是这个小得不起眼的工具让我理解了一件事所谓的 AI 编程助手本质上就是“上下文提取 模型请求 结果解析”三段式。看懂了这个你就不难造出更顺手的版本。2.3 为什么坚持命令行因为命令行是唯一能无缝嵌入 Git 工作流的东西。你可以在 commit 之前自动跑一遍审查可以在写完代码后用一个命令让它生成变更说明可以在早上自动给它喂昨天的 git diff让它输出一份“项目日报”。这些自动化动作GUI 工具很难稳定做到。而且命令行没有视觉噪音。你不会因为界面太漂亮而分心也不会被一堆面板参数吓退。它就是一个 prompt一个输出。简单直接。3. 自己动手从零搭一套可用的 free-claude-code3.1 准备运行环境先准备三样东西。第一Python 3.11 以上。下文脚本会用到argparse、json、urllib.request这些都在标准库里不需要额外安装第三方包。第二一个模型服务入口。我建议你先在本地启动一个兼容 HTTP 接口的模型服务进程监听127.0.0.1:8080路径为/v1/chat/completions。这种服务框架非常常见大多数开源模型服务端都能做到。如果没有本地条件也可以先申请一个云端免费接口把请求 URL 和 Key 填进环境变量。第三一个测试项目目录。随便找个小仓库最好里面有几个不同语言的代码文件方便后面测试过滤和解析功能。所有配置都别写死在脚本里用环境变量读取。比如MODEL_BASE_URL、MODEL_API_KEY、MODEL_NAME。这样脚本可以随时切换本地或云端。3.2 写第一个极简外壳脚本下面是我现在还在用的核心脚本我把它放在/usr/local/bin/cacode这样任何目录下都能调用。它支持三个子命令explain解释文件、check审查文件、commit从标准输入读入 git diff 生成提交说明。#!/usr/bin/env python3 import argparse import json import os import sys import urllib.request MODEL_BASE os.environ.get(MODEL_BASE_URL, http://127.0.0.1:8080/v1) MODEL_NAME os.environ.get(MODEL_NAME, local-model-7b) API_KEY os.environ.get(MODEL_API_KEY, ) def ask_model(system_prompt, user_prompt): payload { model: MODEL_NAME, messages: [ {role: system, content: system_prompt}, {role: user, content: user_prompt[:6000]}, ], temperature: 0.1, } req urllib.request.Request( f{MODEL_BASE}/chat/completions, datajson.dumps(payload).encode(utf-8), headers{Content-Type: application/json}, ) if API_KEY: req.add_header(Authorization, fBearer {API_KEY}) with urllib.request.urlopen(req, timeout120) as resp: data json.loads(resp.read().decode(utf-8)) return data[choices][0][message][content].strip() def read_file(path): with open(path, r, encodingutf-8, errorsignore) as f: return f.read() def cmd_explain(args): content read_file(args.file) prompt f请用中文解释这个文件的核心逻辑按模块/函数/关键变量三个层次说明\n\n\n{content}\n print(ask_model(你是一个资深代码阅读助手只依据给定代码做解释不要编造外部信息。, prompt)) def cmd_check(args): content read_file(args.file) prompt f请审查以下代码按问题严重程度列出真实存在的问题。没有把握的问题不要提。\n\n\n{content}\n print(ask_model(你是一个严格的代码审查员只报告代码中确实存在的问题不客套。, prompt)) def cmd_commit(args): diff sys.stdin.read() prompt f根据下面的 git diff生成一条符合 Conventional Commits 规范的提交信息控制在 80 字以内。\n\n\n{diff}\n print(ask_model(你是提交信息助手遵循 Conventional Commits不写与变更无关的内容。, prompt)) def main(): parser argparse.ArgumentParser(descriptionfree-claude-code 命令行外壳) sub parser.add_subparsers(destcommand, requiredTrue) p_explain sub.add_parser(explain, help解释指定文件) p_explain.add_argument(file) p_check sub.add_parser(check, help审查指定文件) p_check.add_argument(file) p_commit sub.add_parser(commit, help根据 diff 生成提交信息) p_commit.add_argument(--diff, actionstore_true, help从 stdin 读取 diff) args parser.parse_args() if args.command explain: cmd_explain(args) elif args.command check: cmd_check(args) elif args.command commit: cmd_commit(args) if __name__ __main__: main()运行方式很简单export MODEL_BASE_URLhttp://127.0.0.1:8080/v1 export MODEL_NAMElocal-model-7b cacode explain src/worker.py cacode check src/worker.py git diff | cacode commit这个脚本里的关键细节是我调小了一件事temperature 0.1。代码审查和提交信息生成这类任务我要的是稳定和准确不是天马行空。温度越高模型越“敢编”对于代码场景不是好事。3.3 把审查接入 Git 钩子脚本本身只是个手动工具接上 Git 钩子才是自动化的开始。我写过这样一个 pre-commit 钩子放在.git/hooks/pre-commit作用是只检查本次暂存区里改动的代码文件#!/bin/sh for file in $(git diff --cached --name-only --diff-filterACM -- *.py *.js *.ts *.go); do echo free-claude-code check: $file cacode check $file || echo 审查完成警告信息见上。 done exit 0记得执行chmod x .git/hooks/pre-commit否则钩子不会运行。为什么只检查暂存区而不是全量扫描仓库因为全量扫描会跑很久而且历史遗留问题一大把模型刷出来的警告你根本看不完。只检查“你这次正在改的东西”信息量刚好也不会因为老代码里的历史问题把提交卡住。我还设计了一个 prepare-commit-msg 钩子用于自动生成提交信息草稿。它会在编辑器打开之前把建议写进提交信息文件你依然有最终修改权#!/bin/sh if [ -z $2 ]; then git diff --cached | cacode commit $1 2/dev/null || true fi注意不要阻塞提交。模型如果临时不可用就让用户自己写提交信息不要因为一个辅助工具把正常开发流程打断。3.4 加一层项目地图脚本跑了一周后我发现一个明显问题直接塞文件内容给模型模型经常缺乏“项目背景”。比如它不知道这个文件在整体架构中处于哪一层不知道依赖关系于是回答会显得零碎。解决办法是加一层项目地图。在提示词前面插入一棵目录树但要做过滤tree -I node_modules|.git|dist|build|__pycache__|*.pyc /tmp/project_map.txt然后把地图和文件内容一起交给模型。提示词变成这是项目的目录结构 {project_map} 现在请分析这个文件 {file_content}这一层让模型回答时能带上上下文。比如看到core_worker.py时如果目录树显示它位于src/services/而被main.py引用模型就能猜测这是一个服务组件。虽然它不能真正运行代码但回答的“命中率”高很多。4. 实际用下来的体验与常见问题4.1 典型场景老项目里查一个诡异的数据丢失问题有一次我在一个模拟项目 X 里遇到怪事某跨平台系统每天凌晨跑批偶发丢数据。看日志看不出明显异常异常栈也没报错。我懒得一行行追就用 free-claude-code 帮忙定位。第一步cacode explain core_worker.py让它把整个脚本的流程讲清楚。模型输出了三段初始化阶段、拉取数据阶段、写回结果阶段。第二步我把重点放在“写回结果阶段”因为它最可疑。我直接发一条更针对的提示词虽然脚本没提供专门接口但用现成的check命令也可以只要把文件换成同一个文件再在提示词里人工追问。这里我不会临时写死提示词而是再写一个简单别名请求cat core_worker.py | head -200 | sed -n 120,180p | cacode check /dev/stdin 2/dev/null || true当然这种方式需要脚本支持/dev/stdin。我在实际版本里加了-f -参数表示从标准输入读文件。然后模型输出一条关键怀疑在第 156 行result使用了在if分支里才定义的batch_id如果某次条件不满足变量是空的但程序没有报错只是把空值写入下游表。我顺着去看果然是作用域和初始化顺序的问题。整个定位过程不到十分钟比我逐行看快了不止一倍。这类问题用 GUI 助手也能查但 CLI 的好处是可以把同样的问题丢给定时任务跑。后来我把这个场景写成了脚本每次跑批前自动检查一次核心脚本出了问题直接钉到终端横幅上。4.2 常见问题速查表问题表现可能原因解决方式模型回答明显在胡编提示词缺少事实约束在 System Prompt 里写明“只根据给定代码回答不要猜测”单次响应内容太长被截断上下文超出窗口分段读取代码按函数或文件拆分不要一次全塞本地模型回答东拉西扯模型太小或量化太低至少换到 7B 级别模型优先用中低量化请求频繁被限流触发云端频控加退避重试批量任务放到低峰时段Git 钩子不执行没有执行权限或解释器路径不对检查chmod x确认首行#!/bin/sh路径审查结果里夹带无关建议上下文里混入了无关文件完善扩展名过滤和.gitignore映射脚本日志里泄露了请求体自己打印了调试信息删除对请求体完整打印只保留 HTTP 状态码和耗时这几个问题我全踩过。尤其是“胡编”那个刚搭好前三天模型看到代码里少个return会一本正经推理出一堆不存在的继承关系。加了严格的系统提示词后情况好了很多。你只能根据用户提供的代码片段回答。 如果代码中没有提到某个类或函数不要假设它存在。 如果无法确定直接说“代码中没有足够信息”。这句话值不少钱。4.3 成本与收益复盘我这套方案跑了大半个季度来算一笔账。本地模型运行的功耗按一台旧笔记本算平均功率大概 30 瓦到 45 瓦。每天跑两小时一个月电费大概两三块钱。云端免费额度正常使用频率完全够偶尔排队但基本不触发限流。真正的成本是初期的调试时间写第一个脚本花了两天调提示词和钩子花了一周。但一次投入长期复用。要注意的是接入任何云端接口时千万别在脚本里硬编码密钥。我用环境变量管理而且绝不把含密钥的日志提交到 Git 仓库。钩子脚本里如果打印了请求体也只是打印到本地终端不至于外泄。但凡是会进仓库的东西我一律不写密钥。后续扩展方向也很多。比如给文件内容做缓存同一份代码只在修改后再请求模型比如加一个简单的向量索引让模型只检索相关的函数定义再比如把 free-claude-code 接到 cron 任务里每天早上输出一份项目状态速报。这些功能不一定都要做先解决最疼的问题。4.4 一条小技巧先跑通再优化如果你也想折腾 free-claude-code我从实际使用中给出的建议是先跑通再优化。别一开始就想做一个全量级的 IDE 插件也别上来就搞向量检索。先用最简单的方法把一条命令跑通选择一个小文件发给模型打印结果。然后逐步加参数、加钩子、加过滤规则。每加一个功能就有一个稳定的参照物。我在实际使用中发现最耗时间的不是写脚本而是调提示词。同一个代码文件不同提示词出结果的质量差异巨大。所以不妨先固定一组提示词跑一星期摸清楚模型的脾气再迭代。free-claude-code 不是终点它是一套“把工具拽回自己手里”的思考方式。你不需要等厂商发布新功能自己想要什么就给它加一个子命令。这种掌控感是任何订阅制产品都给不了的。