说实话我第一次看到“claude-code-action”这个项目名第一反应是“这应该是某个用来在CI流水线里跑Claude Code的Action封装”。后来顺着这条线折腾了几周发现事情没那么简单Claude Code的Action能力——不管是你日常在终端里让它干一次性的重构任务还是把它作为GitHub Action集成到自动化流程中——底层都是同一套机制在起作用那就是“把一句自然语言目标拆解成一系列真实可执行的操作序列”。如果你现在还停留在“打开终端让Claude Code帮我写个函数、修个bug”的阶段这篇内容建议先收藏。我今天不聊基础对话用法重点是把Claude Code从“对话式助手”变成“自动化执行引擎”的完整路径Action的底层逻辑是什么、环境准备有哪些隐藏坑、怎么接入不同模型、如何在CI里面跑起来最后再把我踩过的坑和排查思路原样交给你。内容偏实操适合已经装了Claude Code、想让它在项目里真正独当一面的开发者。1. Action不是按钮是Claude Code的核心执行机制1.1 从Agent循环说起Claude Code的底层是一个典型的Agent循环它拿到你的目标之后不会一次性生成一个“标准答案”然后结束而是进入一个“思考→调用工具→观察结果→再思考”的循环。每一步循环都可能触发真实动作比如读取文件、搜索代码、执行shell命令、修改文件、启动子代理甚至在不放心的时候停下来向你申请权限。我在一次重命名接口的任务里观察过它的行为日志大致是这样▶ Thinking... ☰ Read server/util.js ▶ Thinking... ✏️ Edit server/util.js ✏️ Edit server/util.js ▸ Execute tests这就是Action的骨骼。理解了这个循环就能明白为什么Claude Code不是普通聊天机器人——它的每次“回复”背后都可能是一连串有副作用的真实操作。它会自己读代码、自己改代码、自己跑测试、看到失败再回来继续改整个过程不需要你手动把上下文喂给它。这也是“claude-code-action”这个项目名背后真正值钱的东西action不是某个特定按钮而是这套可自主推进的执行引擎。1.2 工具集与权限边界Claude Code暴露给Agent的工具大致有这些Read、Edit、Write、Glob、Grep、Bash、TodoWrite、Task、WebFetch等。这里面Edit和Bash是典型的“有副作用”工具WebFetch涉及外部访问Task会递归产生子代理。你真正要做的不是让Agent“一路绿灯”而是明确告诉它哪些事情可以直接做、哪些必须先问。权限配置有三个梯度allow直接执行、ask每次询问、deny禁止执行。默认大多数有副作用的操作都会进入ask模式所以交互式使用时会频繁看到权限弹窗。如果你不想每次都被打断可以在settings文件里预置规则后面第3节我会详细讲配置文件的组织方式。1.3 从对话思维切换到任务脚本思维把思维从“对话”切到“任务分配”之后很多场景立刻不一样了。举个例子我之前想重构项目里一个被几十处调用引用的工具函数手动把每个调用点复制给AI根本不现实。后来我直接这样输入重构 src/date-utils.ts 中的 parseDate 函数 让它在解析失败时返回 null 而不是抛异常 并更新所有调用点。最后跑一遍完整测试。Claude Code自己读了源码、把所有调用点找出来、逐个修改、跑测试、把失败的单测修好全程大概几分钟。关键在于我给了一个“验收标准”很硬的任务测试通过、类型检查干净。如果你的任务描述里没有这种可量化的验收条件Agent容易跑偏这一点后面排错章节还会再展开。2. 从安装到能跑环境准备里最容易忽视的细节2.1 命令行安装在Mac和Linux上安装基本就是一条命令npm install -g anthropic-ai/claude-code装完先验证版本claude --version要求Node.js版本在18以上太旧版本会直接报错。如果你平常npm全局包装得比较多注意一下全局bin目录是否在PATH里否则会出现“安装成功但claude命令找不到”的尴尬。升级也很频繁建议隔一段时间对比一下本地版本和npm最新版本需要时执行npm update -g anthropic-ai/claude-code2.2 桌面版、编辑器扩展与CLI的关系现在Claude Code已经不再只是终端工具了。VS Code扩展市场里可以直接搜“Claude Code”安装装完侧边栏会多出一个面板本质上是把CLI能力包了一层图形界面。桌面版也出了同样走官方下载渠道。JetBrains系列插件也在逐步跟上。我个人体验是图形面板适合交互式使用比如审查代码、边看边改但要真正发挥Action能力还是在终端里给非交互模式传参数更方便因为可以脚本化。后面第4节会重点讲非交互模式那是自动化工作流的基础。2.3 Windows上必做的虚拟化设置如果你在Windows上运行Claude Code可能会遇到这样一个报错Claudes workspace requires the virtual machine platform on Windows. Enable...我第一次遇到的时候没太当回事以为重启就好。重启后发现还是不行后来才搞明白Claude Code的“workspace”依赖Windows虚拟化能力它会在一个隔离沙箱环境里执行文件操作和命令避免Agent的动作全部直接落在宿主系统上。这是它工程上比较特别的设计——不是普通桌面软件。解决办法打开控制面板 → 程序和功能 → 启用或关闭Windows功能找到“虚拟机平台”并勾选重启系统重启之后再执行claude --version这个报错就不会再出现了。如果你安装的是Windows 11专业版以上这个过程基本顺滑家庭版界面选项可能存在差异那就先从系统功能列表确认。2.4 密钥准备与基础启动安装配置完后第一次启动前还需要准备好API密钥。Claude Code默认通过Anthropic的API调用Claude系列模型因此需要把密钥放到环境变量里export ANTHROPIC_API_KEY你的密钥然后直接敲claude进入交互模式。如果你有多个项目要用不同密钥Windows下可以借助系统环境变量面板管理Mac/Linux可以在shell配置文件里写入。下一节会讲到更规范的做法把密钥放在项目级settings里面这样多个项目互不干扰。3. 模型接入与配置体系为什么你配了DeepSeek却没生效3.1 核心环境变量的角色Claude Code的模型路由靠三个环境变量控制环境变量作用ANTHROPIC_API_KEY调用模型服务的密钥ANTHROPIC_MODEL指定模型名称ANTHROPIC_BASE_URL指定API网关地址默认情况下这三个变量都不用显式设置——CLI会用Anthropic官方默认值。但是一旦你要接第三方模型服务或者你要把密钥收进项目配置里这三兄弟就成了主角。3.2 DeepSeek、Qwen等第三方模型的接入现在社区里很多人在讨论“Claude Code接入DeepSeek”实际操作原理其实非常直白第三方模型服务商提供一套兼容Anthropic接口的网关你把ANTHROPIC_BASE_URL指到网关、把ANTHROPIC_API_KEY换成第三方服务商的Key、把ANTHROPIC_MODEL设为对方模型名就完成了。我在自己机器上试过的配置大概是这样的export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_API_KEY你的DeepSeek密钥 export ANTHROPIC_MODELdeepseek-chat用Qwen也是一样的套路改成对应的网关地址和模型名就行。Mac上用qwen key跑CLI本质也是这套配置并没有额外魔法。这里必须提醒一句不是所有模型都适合这种Agent模式。Claude Code的工具调用依赖模型的function calling能力如果模型本身不具备稳定可靠的工具调用能力你会在日志里看到“答非所问”“工具乱调”之类的状况。所以接了第三方模型之后别急着上复杂任务先做一个最小测试让它读一个文件、改一行内容、跑一次命令看看工具调用的链路通不通。3.3 配置文件层级与优先级很多“为什么我改了配置没生效”的帖子根因都是没搞清楚配置优先级。我自己梳理下来的层级大致是这样的命令行参数例如--model环境变量项目级.claude/settings.json用户级~/.claude/settings.jsonCLI内置默认值层级高的会覆盖层级低的。如果你在命令行传了--model deepseek-chat那么环境变量里的ANTHROPIC_MODEL就不会被读取这是一个很容易踩的坑。排查配置问题我推荐一条命令claude --settings它会打印出当前合并后的最终配置一眼就能看到哪个模型、哪个Base URL真正生效不用瞎猜。3.4 settings.json里的权限配置如果你希望某些工具自动放行、某些命令永远禁止不要每次都在弹窗里手动选择直接在settings里写死。用户级文件在~/.claude/settings.json项目级在.claude/settings.json。比如一个公共配置{ permissions: { allow: [ Read, Glob, Grep, Bash(npm run test), Bash(git status) ], deny: [ Bash(git push), Bash(rm -rf *) ], ask: [ Edit, Write ] } }这样测试命令可以直接执行危险的删除命令和push操作被直接拒绝文件编辑还是每次询问。这就是Action工作流中安全边界的基础。记住一句话你不是要让Agent“不能做”而是要让它“按你的规则做”。3.5 CLAUDE.md给Agent看的项目操作手册settings管的是“工具使用规则”而CLAUDE.md管的是“项目该怎么干活”。它会被自动注入到Agent的上下文里相当于项目操作手册。比如在项目根目录写一个CLAUDE.md# 项目约定 - 包管理器使用 pnpm禁止使用 npm - 测试命令pnpm test -- --run - 后端代码位于 server/前端代码位于 web/ - 提交信息遵循 conventional commits 规范这样Claude Code在项目里跑Action时会自动遵循这些约定不会自作主张用npm install或者乱找目录。如果你有好几个项目共用同一个CLICLAUDE.md就是让每个项目各有各的“Action风格”的关键。除了项目根目录用户级~/.claude/CLAUDE.md也可以放通用规则优先级低于项目级。4. 构建一个可复用的Action工作流从单条命令到CI流水线4.1 先定一个真实场景空谈概念没有意义我拿一个真实任务举例把一个旧Node.js模块重构为TypeScript用Vitest补单元测试同时保证对外接口行为不变。手工做我大概要四十分钟大部分时间往返于“改代码→跑测试→修问题”。用Claude Code的Action机制这个流程可以被固化成一条命令直接在终端里执行。4.2 非交互模式--print 才是自动化的核心平时交互模式是打开一个反复对话的shell但自动化场景需要一次性执行完就退出这时候--print参数很有用。它的语义是把prompt作为输入让Claude Code执行完任务并把最终结果打印到标准输出然后退出。基本用法echo 将 server/util.js 重构为 TypeScript用 Vitest 补齐测试确保接口兼容最后运行测试并修复失败。 \ | claude --print \ --allowedTools Read,Edit,Write,Glob,Grep,Bash \ --model deepseek-chat--allowedTools后面跟的必须是工具官方名称多个工具名用逗号分隔。这样运行起来之后只要prompt清晰、验收标准明确Claude Code就会自己完成循环不需要你在旁边点权限按钮。如果你要拿结果做后续处理可以加--output-format json它会输出结构化JSON方便脚本解析。想看到它到底执行了哪些工具调用加--verbose调试阶段强烈建议打开。4.3 在GitHub Actions里真正用起来“claude-code-action”最常见的使用场景就是在GitHub Actions里跑代码审查或者自动修复。我自己维护的一个仓库里配了这样一个workflow用于PR自动审查name: claude-code-review on: pull_request: jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm install -g anthropic-ai/claude-code - name: Run Claude Code review env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | echo 请审查本次PR的diff重点关注逻辑错误、安全漏洞和边界条件。输出格式优点/问题/改进建议。 \ | claude --print \ --allowedTools Read,Glob,Grep \ -o text review.md这个workflow做的事情就是拉代码、装CLI、喂一个审查prompt、把结果写到review.md。如果你想在CI里做更激进的事情比如自动修lint问题并提交PR可以把Edit和Write加进allow列表但在CI里放开写入权限需要非常谨慎因为Agent的行为随时可能超预期。这里要说明一下社区里很多封装好的“claude-code-action”项目本质上就是把上面的安装和调用步骤打包成一个可复用的GitHub Action/复合工作流。理解了这个原理你完全可以自己维护一个没必要依赖第三方封装。4.4 Skill把个人经验固化成模板如果你希望Claude Code在某个任务里“按你的套路来”最好的做法不是每次在prompt里重复规则而是写一个Skill。Skill目录里放一个SKILL.md文件目录放用户级~/.claude/skills/或项目级.claude/skills/格式大致如下--- name: ts-migration description: 当需要将 JavaScript 文件迁移到 TypeScript 时使用 --- # TypeScript迁移步骤 1. 先阅读源文件梳理所有导出接口 2. 创建 .ts 文件保持接口名称和签名不变 3. 为每个主要函数编写 Vitest 测试 4. 运行 pnpm test -- --run修复所有失败 5. 更新所有 import 路径为 .ts 后缀Claude Code在收到一个新任务时会根据SKILL.md里的name和description判断是否应该加载这个技能。比如我输入“把util.js迁到TS”它就会自动找到这个技能并按照步骤清单执行。这才是把“Action”真正沉淀下来的方式——团队里每个人都可以贡献技能文件项目经验变成可复用的自动化资产。4.5 Hooks在关键时刻拦截如果说Skill是给Agent“加套路”那么Hooks就是给你的工程规范“加护栏”。settings.json里可以配hooks在PreToolUse、PostToolUse、Notification等时机触发外部命令。比如{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: sh ./scripts/check-dangerous-command.sh } ] } ] } }想象一下Agent准备执行任意Bash命令时先跑一个你写的脚本去检查命令内容发现可疑就拦截并返回错误。这比单纯依赖权限弹窗可控得多。Action一旦进入CI和团队协作场景Hooks几乎是必需品。5. 实战排错我踩过的那些坑和完整排查链路5.1 401 unauthorized: invalid_api_key这个错误的出现频率排第一。报错长这样{ error: { code: invalid_api_key, message: invalid x-api-key } }遇到这种情况按照下面的链路从头排查先确认当前生效的key到底是什么。不要用眼睛猜执行env | grep ANTHROPIC再看一下claude --settings里合并出来的配置。检查key是否带了多余的空格、引号或换行。尤其是从网页控制台复制key的时候很容易多复制一个看不见的字符。检查是否同时配置了别的环境变量把key覆盖了。比如shell配置里写了一个旧的ANTHROPIC_API_KEY而项目settings里又是另外一个值优先级低的会被覆盖。如果接的是第三方模型服务确认ANTHROPIC_BASE_URL和key是否配套。很多人把官方key配到第三方网关或者反过来出错是必然的。还有一点不要在命令行里直接明文传key比如ANTHROPIC_API_KEYsk-xxx claude ...。key会被shell历史记录带到磁盘上安全风险太大。5.2 Windows虚拟化问题再补充前面第2节已经给了解决办法这里补充一点诊断经验如果勾选了“虚拟机平台”重启后依然报错可以先确认系统虚拟化是否在BIOS层面被禁用。打开任务管理器→性能→CPU看“虚拟化”那一栏是不是“已启用”。如果显示禁用那就需要进BIOS打开相关选项。这个问题和Claude Code本身无关是Windows环境问题的常见前置条件。5.3 权限玩脱了Agent会绕路权限系统最微妙的一点在于Agent被拒绝之后它会换一种方式继续尝试看起来非常执拗。我遇到过一次我deny了Bash(pnpm install)它转头用npm install继续尝试。这就是典型的“绕路行为”。解决方案有三个在deny列表里把整个命令家族都写进去比如同时denypnpm install和npm install在prompt里明确写“不要尝试绕过权限限制”它会遵守这条指令把所有命令限制在项目目录内别让它有到处撒野的空间5.4 Token消耗失控Action模式下最烧钱的地方“Action”模式最容易失控的是token消耗。Agent可能反复读同一个文件、开太多子代理最终账单感人。我自己的控制手段大概是限制Task子代理数量不需要深度搜索时不要把问题抛给子代理提示词里明确“优先使用Grep定位不要整个文件读取”复杂任务拆成多个小Action来执行而不是塞进一个巨型prompt在CLAUDE.md里写“任何文件只读一次不要在后续步骤中重新读取”这些约束不是官方强制的但实测下来能省不少token而且执行稳定性更高。5.5 千万不要轻易跳过权限那条--dangerously-skip-permissions参数真的一键跳过所有权限询问执行效率最高但风险也最大。我建议只在完全隔离的CI容器里使用比如临时构建环境、一次性代码分析任务。本地开发机上绝对不要开因为一旦它决定执行某个危险操作你连个拦截的机会都没有。我有一次在本地用这个参数跑任务它顺手删掉了一个未提交的分支好在git reflog还能救回来。从那以后我再也没在本地开过这个开关。写在最后小步放权这是我用的最稳的策略如果要我从这一整段经验里挑一句最有价值的话那就是别一开始就给Agent全部放权哪怕是在CI里也一样。我自己现在的通用策略是“小步放权”——先只给Read、Glob、Grep这类只读工具跑通整体流程确认不会跑偏后再加Edit和Write最后如果确实需要它执行命令才逐步放开特定的Bash命令白名单。每一步都观察实际行为再决定是否往前走一步。这样做的核心原因很简单Claude Code的Action能力确实很强但强不等于不需要约束。给它明确的规则、有边界的权限、可验证的验收标准它就能稳定地替你干活反过来一旦你把这三样丢掉它的自主性随时可能变成不确定性。很多生成式AI编程工具出事的案例问题不在于模型能力不够而在于使用它的环境太过宽松。这个道理用过一段时间Claude Code的人应该都能体会。
