1. 项目概述一个完全运行在GitHub Actions上的AI助手如果你和我一样对AI代理Agent的潜力着迷但又对部署和维护服务器、管理API密钥、处理Webhook回调这些“脏活累活”感到头疼那么gitclaw这个项目绝对会让你眼前一亮。简单来说gitclaw是一个完全运行在GitHub Actions上的个人AI助手。它的核心思想非常巧妙将GitHub Issues当作聊天界面将Git仓库当作记忆存储将GitHub Actions当作计算引擎。你不需要准备任何服务器不需要配置任何反向代理甚至不需要离开GitHub这个你每天都在用的平台。这就像是把OpenClaw这样的智能助手彻底“塞”进了GitHub的生态里让它变得无比轻量和易于上手。这个项目的灵感来源于OpenClaw但它的实现路径截然不同。OpenClaw通常需要一个长期运行的服务器来监听事件、维护会话状态。而gitclaw则利用了GitHub Actions的无服务器特性——按需触发用完即走。每一次你创建Issue或者评论都会触发一次Action工作流。这个工作流会启动一个临时的运行环境加载AI代理让它处理你的请求然后把结果包括对话历史和任何文件修改提交回仓库最后工作流结束所有临时资源被释放。这种模式带来的好处是显而易见的零基础设施成本、天然的版本控制、以及GitHub Actions免费额度内的极低成本运行。那么它具体能做什么想象一下你可以把它当作一个24小时在线的项目协作者。你可以开一个Issue说“帮我初始化一个React项目并配置好Tailwind CSS和TypeScript。” 几分钟后你会发现仓库里多了一个完整的项目骨架并且AI在Issue里回复了你解释了它做了什么。接着你可以在同一个Issue下评论“很好现在请添加一个导航栏组件。” AI会记住之前的上下文继续工作。更酷的是所有的对话、AI的思考过程、以及它对项目文件的每一次修改都会被完整地记录并提交到Git仓库中。这意味着你拥有了一份可追溯、可回滚的完整项目演进日志。无论是搭建一个静态博客、编写工具脚本还是迭代一个复杂的应用原型gitclaw都能让你通过“聊天”的方式驱动开发。2. 核心架构与工作原理拆解要理解gitclaw为什么能工作我们需要深入它的架构。这不仅仅是一个简单的“GitHub Actions调用AI API”的脚本而是一个精心设计的、以Git为中心的状态管理系统。2.1 基于事件的触发与响应机制gitclaw的核心驱动力是GitHub的Webhook事件。在项目根目录的.github/workflows/agent.yml文件中定义了工作流的触发条件。通常它会监听issues和issue_comment事件。当你创建一个新Issue时issues.opened事件被触发当你在一个已有的Issue下评论时issue_comment.created事件被触发。GitHub会自动将这些事件及相关负载Payload比如Issue的编号、标题、内容、评论者信息传递给对应的Actions工作流。工作流被触发后会启动一个全新的、干净的运行器Runner环境。这个环境是临时的基于Ubuntu或其它系统镜像。工作流的第一步通常是检出Checkout你的代码仓库这样AI代理就能访问到项目现有的所有文件以及state/目录下的历史会话数据。接下来工作流会安装必要的运行环境比如Node.js、Bun和项目依赖然后执行核心的AI代理命令。注意由于GitHub Actions的运行器是临时的且网络环境可能受限所有依赖都必须能在工作流中快速安装或已经容器化。gitclaw选择了bun作为运行时并依赖pi-mono这个AI代理框架正是因为它们具有启动快速、依赖简单的特点。2.2 状态管理Git作为单一事实来源这是gitclaw设计中最精妙的部分。大多数AI应用需要数据库如Redis、PostgreSQL来存储会话状态和记忆。gitclaw反其道而行之直接用Git仓库来存储一切状态。在仓库根目录下有一个state/文件夹其结构如下state/ ├── issues/ │ └── 1.json # 将Issue #1映射到其对应的会话文件 └── sessions/ └── 2026-02-04T10:30:00.000Z_abc123.jsonl # Issue #1的完整对话记录issues/目录这里存放的JSON文件以Issue编号命名如1.json。这个文件是一个简单的映射表内容可能类似于{sessionFile: sessions/2026-02-04T10:30:00.000Z_abc123.jsonl}。它的作用是将一个GitHub Issue与一个具体的会话记录文件关联起来。这样无论何时这个Issue被触发代理都能快速找到它上次的聊天历史。sessions/目录这里存放的是实际的对话记录文件通常以时间戳和随机ID命名确保唯一性。文件格式是JSONLJSON Lines即每一行都是一个独立的JSON对象记录着一次完整的消息交换用户输入、AI思考过程、工具调用、最终回复。这种格式易于追加写入也便于流式读取。这种设计带来了几个革命性的优势持久化与版本控制会话历史不再是易失的它被完整地保存在Git中。你可以用git log查看对话的演变用git diff查看AI对项目文件做了哪些修改甚至可以回滚到任何一个历史版本。这为调试和审计提供了极大的便利。长期记忆与自我检索由于所有历史对话都以文本形式存储在仓库里AI代理可以被赋予“自我检索”的能力。通过工具调用它可以grep或搜索sessions/目录下的旧对话来回忆之前讨论过的内容、做出的决策或者总结项目进展。这模拟了某种形式的长期记忆。无状态代理AI代理本身即pi-mono在工作流执行期间是无状态的。它每次启动都从零开始但它会从state/目录加载特定Issue的会话历史文件从而“恢复”到上次对话的状态。处理完成后它将新的对话行追加到会话文件并将所有更改包括更新的会话文件和可能被修改的项目文件一次性提交回仓库。这样状态被安全地持久化而代理则可以保持简洁和无状态。2.3 代理核心pi-mono框架的能力gitclaw的“大脑”是pi-mono一个由Mario Zechnerbadlogic开发的开源AI编码代理框架。它不是一个简单的ChatGPT包装器而是一个具备工具使用Tool Use能力的智能体。在工作流中通过bunx pi命令启动代理时会传递当前Issue的标题和内容作为初始输入。pi-mono代理会规划理解用户的自然语言请求。工具调用根据需求决定调用哪些工具。它内置的工具可能包括read读取仓库中的文件。write创建或修改文件。grep/find在文件中搜索内容或查找文件。ls列出目录内容。run执行Shell命令需要谨慎授权。执行与观察调用工具获取结果例如读取了一个配置文件的内容或执行npm install后的输出。思考与响应基于工具返回的结果进行下一步规划或生成最终的自然语言回复给用户。整个过程中代理的“思考”步骤它为什么选择这个工具、如何解析结果也会被记录下来存入会话文件。这就是为什么会话文件是JSONL格式它完整记录了AI的推理链。用户交互反馈代理在“忙碌”工作时会在Issue评论下留下一个眼睛表情作为反应Reaction这是一个非常直观的进度提示。当工作完成并回复评论后它会移除这个反应。这个小细节极大地提升了交互体验让你知道代理正在处理中而非没有响应。3. 从零开始部署与配置实战理解了原理接下来我们动手把一个全新的gitclaw实例跑起来。这个过程大约需要10-15分钟。3.1 第一步 Fork仓库与基础准备首先访问SawyerHood/gitclaw的GitHub仓库页面点击右上角的Fork按钮。这会在你的账号下创建一个完整的副本。Fork完成后进入你自己的这个新仓库。实操心得我建议在Fork后立即将仓库的默认分支名从可能存在的main或master统一改为main以避免后续Actions工作流在分支引用上出现意外问题。可以在仓库的Settings - Branches里修改默认分支。接下来我们需要给这个仓库注入“灵魂”——AI能力。gitclaw默认使用Anthropic的Claude模型通过API因此你需要一个Anthropic API密钥。访问 Anthropic官网 注册并获取API Key。进入你Fork后的仓库点击Settings选项卡。在左侧边栏找到Secrets and variables下的Actions。点击New repository secret按钮。Name输入ANTHROPIC_API_KEY必须完全一致大小写敏感。Value粘贴你从Anthropic控制台复制的API密钥。点击Add secret。至此最关键的配置就完成了。你的API密钥会以加密的方式存储在GitHub中工作流运行时可以安全地访问它而不会在日志中明文暴露。3.2 第二步深度解析与定制工作流文件部署的核心是.github/workflows/agent.yml文件。让我们打开它逐部分解析其作用并看看如何根据自己需求定制。name: AI Agent on: issues: types: [opened, edited] issue_comment: types: [created]on部分定义了工作流的触发器。这里配置为当Issue被创建、编辑或Issue评论被创建时触发。你可以进行精细化控制例如types: [opened]只响应新Issue不响应编辑。添加labels: [ai-help]来只处理带有特定标签的Issue避免无关的Issue触发Agent消耗额度。jobs: agent: runs-on: ubuntu-latest if: github.event.sender.login github.event.repository.owner.login || contains(github.event.repository.collaborators.*.login, github.event.sender.login) permissions: contents: write issues: write pull-requests: writejobs.agent定义一个名为agent的任务。runs-on指定在最新的Ubuntu系统上运行。if条件安全核心这是一个至关重要的安全限制。它确保工作流只对仓库所有者owner、成员members和合作者collaborators触发。github.event.sender.login是触发事件的用户github.event.repository.owner.login是仓库所有者。这个条件防止了公开仓库被任何路过的人通过创建Issue来滥用你的API密钥和Actions额度。permissions这里授予了工作流所需的权限。contents: write允许它向仓库提交代码issues: write允许它在Issue下回复评论和添加反应pull-requests: write是pi-mono框架可能需要的权限例如创建PR。steps: - name: Checkout repository uses: actions/checkoutv4 with: token: ${{ secrets.GITHUB_TOKEN }} fetch-depth: 0检出仓库使用actions/checkout动作。fetch-depth: 0意味着拉取完整的历史记录这对于某些Git操作可能是必要的。- name: Setup Bun uses: oven-sh/setup-bunv1 with: bun-version: latest安装Bunpi-mono是一个使用Bun运行时的项目所以这里安装了最新的Bun环境。- name: Install dependencies run: bun install安装依赖运行bun install根据仓库里的package.json和bun.lockb文件安装pi-mono等所有依赖。- name: Run AI agent env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | bunx pi \ --provider anthropic \ --model claude-3-5-sonnet-20241022 \ --tools read,write,grep,find,ls,run \ --thinking high \ --issue-number ${{ github.event.issue.number }} \ --issue-title ${{ github.event.issue.title }} \ --issue-body ${{ github.event.issue.body || github.event.comment.body }}运行AI代理这是最核心的一步。它设置了环境变量ANTHROPIC_API_KEY然后执行bunx pi命令。--provider和--model指定使用的AI服务提供商和模型。默认是Anthropic的Claude 3.5 Sonnet。你可以根据需要更换例如--provider openai --model gpt-4-turbo-preview但需要同时设置对应的API密钥秘密如OPENAI_API_KEY。--tools定义代理可以使用的工具列表。这是安全性和功能性的关键控制点。默认给了read, write, grep, find, ls, run全部权限。run工具允许执行任意Shell命令功能强大但也有风险。如果你只想让代理做代码分析或文档生成可以改为--tools read,grep,find,ls将其限制为只读。--thinking设置推理强度。high模式会让代理进行更深入、更链式的思考适合复杂任务但也会消耗更多token更贵、更慢。对于简单任务可以移除此参数或设为low。后面的--issue-*参数将GitHub事件的上下文传递给代理使其知道当前正在处理哪个Issue以及内容是什么。3.3 第三步首次运行与验证配置完成后就可以进行“开机测试”了。在你的仓库页面点击Issues选项卡。点击New issue按钮。输入一个简单的标题和内容例如Title:Test: Say hello and create a READMEBody:Please introduce yourself and create a simple README.md file for this gitclaw project.点击Submit new issue。提交后立即切换到Actions选项卡。你应该能看到一个名为“AI Agent”的工作流正在运行显示黄色⚡图标。点击进入可以查看实时日志。你会看到一系列步骤准备环境、安装Bun、安装依赖最后是“Run AI agent”。在代理运行期间回到你刚创建的Issue页面可能会看到评论区域有一个反应。等待1-3分钟取决于任务复杂度和网络工作流完成后你会看到Issue中出现了一条来自github-actions[bot]的评论内容是AI的自我介绍和它执行的操作说明。仓库根目录多了一个README.md文件。state/目录下生成了新的issues/1.json和sessions/下的一个会话文件。提交历史多了一次提交消息通常是“Update state and project files”。恭喜你的个人AI助手已经正式上线了你可以继续在这个Issue下评论进行多轮对话。4. 高级用法、场景与定制技巧基础功能跑通后我们可以探索gitclaw更强大的应用场景和定制化玩法。4.1 场景一自动化项目初始化与脚手架这是最直接的应用。你可以创建一个“项目蓝图”Issue。Title: 初始化Next.js 15项目包含App Router、Tailwind CSS和Shadcn/ui Body: 请执行以下操作 1. 使用create-next-applatest初始化一个TypeScript项目启用App Router和Tailwind CSS。 2. 安装并配置Shadcn/ui组件库初始化按钮、卡片、输入框组件。 3. 在app/page.tsx中创建一个简单的示例页面展示这些组件。 4. 更新package.json中的scripts添加lint和format命令。 5. 创建一份简要的开发者指南在CONTRIBUTING.md中。代理会按步骤执行命令、修改文件并在评论中汇报进度。整个过程就像有一个经验丰富的开发者在为你搭建基础框架而且所有操作都被记录在案。4.2 场景二交互式代码审查与重构助手将gitclaw作为代码审查伙伴。当你完成一个功能分支后可以开一个Issue并粘贴一段核心代码或一个Pull Request的diff链接如果代理有网络访问工具。Title: 代码审查用户认证模块重构 Body: 以下是我重构后的用户认证服务代码/src/services/auth.ts。请帮我审查 1. 是否存在潜在的安全漏洞如密码存储、JWT处理 2. 代码结构是否符合SOLID原则有无过度耦合 3. 错误处理是否完备 4. 请提供具体的改进建议如果可能直接给出修改后的代码片段。代理可以读取指定文件进行分析并提出建议。你可以在评论中针对它的建议进行追问和讨论形成一次深度的代码评审会话。4.3 场景三文档生成与知识库维护利用代理的读写和总结能力维护项目文档。Title: 为/src/utils目录下的所有工具函数生成API文档 Body: 请遍历/src/utils目录下的所有.ts文件。 1. 为每个导出的函数生成JSDoc风格的注释如果缺失。 2. 提取这些函数的信息并在/docs/utils-api.md文件中创建一个统一的API参考手册。 3. 手册应包含函数名、描述、参数、返回值和简单的使用示例。代理可以自动完成这项繁琐且容易过时的文档工作并且由于每次运行都是基于最新代码生成的文档也能保持同步。4.4 深度定制调整代理行为与工具链除了修改工作流文件中的--tools和--model你还可以通过其他方式定制提供系统提示词System Promptpi-mono代理的行为很大程度上由系统提示词决定。你可以在仓库中创建一个prompt.txt或类似文件在工作流中通过--prompt prompt.txt参数加载。在这个文件里你可以定义代理的角色“你是一个资深的Python后端工程师”、行事规则“优先考虑代码可读性和性能”、以及禁忌“未经确认不得删除任何生产数据文件”。限制文件访问范围通过修改--tools参数和在工作流步骤中添加前置的路径检查可以限制代理只能访问特定目录如/src而不能触及配置文件或密钥文件所在的目录。集成其他工具GitHub Actions的强大之处在于可以串联多个步骤。你可以在AI代理运行前或后添加其他步骤。例如运行前先运行测试如果测试失败则不让AI代理执行修改。运行后让AI代理生成的代码自动通过prettier格式化或者运行一套linter检查并将结果作为新的评论追加到Issue中。5. 安全、成本与常见问题排查将AI代理与仓库写权限结合安全是重中之重。同时作为免费用户成本主要是GitHub Actions分钟数和API调用费用也需要关注。5.1 安全最佳实践仓库可见性这是第一道防线。如果你用gitclaw处理任何包含敏感信息、未公开代码或私密对话的项目务必将其设置为私有仓库Private Repository。公开仓库下的所有提交、Issue对话、Actions日志默认都是公开可见的。API密钥管理永远不要将API密钥硬编码在代码或工作流文件中。严格按照指南只使用GitHub Secrets存储。定期在AI服务商的控制台轮换密钥。工具权限最小化再次强调--tools参数。对于大多数非开发类任务如文档问答、数据分析移除write和run工具只保留read, grep, find, ls。这能有效防止代理意外或恶意修改、删除文件或执行危险命令。仔细审查提交代理的每次提交都会生成一个Pull Request如果配置了或直接推送到分支。养成习惯在合并前仔细查看diff。AI可能会产生看似合理但有细微错误的代码或者误解你的意图。设置触发条件利用工作流的on:条件进行过滤。例如你可以设置为只处理由你本人github.event.sender.login 你的用户名创建的Issue或者只处理带有bot标签的Issue。5.2 成本控制与额度管理GitHub Actions额度GitHub为免费账户提供一定量的免费Actions分钟数私有仓库额度较少公开仓库较多。每次Agent运行都会消耗分钟数。你可以在仓库的Settings - Actions - General中设置工作流执行的超时时间默认为6小时可调短。在Actions运行日志中关注执行时长优化代理的提示词让任务更聚焦减少不必要的思考循环。AI API成本这是主要成本来源。Claude或GPT的API按Token收费。选择合适模型对于简单任务可以考虑使用更小、更便宜的模型如Claude Haiku或GPT-3.5-Turbo通过修改--model参数切换。控制对话长度冗长的会话历史会作为上下文传入增加Token消耗。虽然gitclaw的存储机制很棒但你可以定期手动清理或归档旧的、不活跃的Issue会话文件。设置预算提醒在Anthropic或OpenAI的控制台设置每月使用量预算和警报防止意外超支。5.3 常见问题与排查实录即使配置正确你也可能会遇到一些问题。下面是一个快速排查指南问题现象可能原因解决方案Actions工作流根本没触发1. 仓库的Actions功能未启用。2. 工作流文件不在默认分支。3..github/workflows/agent.yml文件语法错误。1. 去Settings - Actions - General确认“Allow all actions”已启用。2. 确保工作流文件在main分支。3. 使用在线YAML校验器检查文件格式。工作流触发但立即失败1.ANTHROPIC_API_KEY密钥未设置或名称错误。2.bun install失败依赖问题。1. 双重检查Secret的名称是否完全匹配并确认密钥有效。2. 查看失败步骤的日志可能是网络问题。尝试在本地运行bun install看是否有依赖冲突。Agent运行失败报权限错误1.GITHUB_TOKEN权限不足。2. 代理尝试访问仓库外的路径或执行被禁止的命令。1. 在工作流中检查permissions设置确保有contents: write。2. 检查代理执行的命令日志。如果涉及敏感操作考虑收紧--tools权限。Agent回复了但没有修改文件或提交1. 代理认为任务已完成仅对话。2. 文件系统操作失败但未在日志中明显报错。3. Git配置问题用户名、邮箱。1. 在提示词中明确指令“请将修改提交到仓库”。2. 查看Agent运行的详细日志搜索“error”或“failed”。3. 工作流中可能需要配置Git用户信息git config。每次评论都创建新会话没有记忆state/目录下的映射文件或会话文件未能正确生成或读取。检查工作流是否有对state/目录的读写权限。查看首次运行后state/目录内是否生成了文件。确保fetch-depth: 0以便能访问完整历史。API调用费用增长过快1. 任务过于复杂导致长上下文和高思考步数。2. 模型选择太昂贵。3. 被恶意触发公开仓库。1. 拆分复杂任务为多个小Issue。2. 切换到成本更低的模型进行测试。3. 为公开仓库添加上文提到的if条件限制触发者。我个人在实际使用中的体会是gitclaw最适合的场景是中小型、迭代式的开发任务和知识性工作。它不是一个全能的自动化解决方案但在“将模糊想法转化为具体代码或文档”这个环节上它极大地降低了心流中断的成本。你不需要离开编码环境去另一个AI工具提问再把答案复制回来。整个对话和产出都紧密集成在你的项目时间线里。最大的惊喜来自于它的“记忆”能力隔了一周再打开一个老Issue问“我们上次为什么决定用这种架构”AI能直接从历史提交中找回当时的讨论上下文这种体验是革命性的。当然你需要对它的输出保持“代码审查者”的心态永远不要盲目信任但这本就是与任何协作者包括人类合作的最佳实践。