概述

本教程聚焦 Claude Code 在 Agent 模式与自动化 领域的"上云"场景：不再在终端里手动驱动，而是把它挂进 CI/CD 流水线 和 定时调度系统，让它在你睡觉时审查 PR、自愈 Lint、巡检代码健康度。我们将覆盖两条主路径——基于 -p Headless 模式的 GitHub Actions 自建流水线，以及 Anthropic 2026 年 4 月推出的 Claude Code Routines 云端定时 Agent——并给出一个可直接套用的"每周代码健康巡检"完整案例。适合已掌握 Claude Code 交互用法、希望把 Agent 推向无人值守自动化的开发者和 DevOps 工程师。

前置条件

• 已安装 Claude Code CLI（npm i -g @anthropic-ai/claude-code），能跑通 claude -p "hello" 的一次性调用
• 一个 Anthropic API Key，或已通过 claude 完成登录（CI 中建议用 API Key）
• 一个 Git 仓库（GitHub 仓库用于 Actions / Routines 的 GitHub 触发器）
• 对 GitHub Actions 的 YAML 语法有基本了解
• （可选）一个 Slack/PagerDuty Webhook，用于接收巡检结果通知

第一步：先想清楚——你要的是哪种自动化？

很多人一上来就写 YAML，结果发现做出来的东西又贵又脆。Claude Code 的 CI/自动化其实有三条不同层次的实现路径，先选对路径能省掉 80% 的返工：

一个简单的判断准则：如果任务你已经能用一句 Claude Code 会话描述清楚，且希望它定时跑，就用 Routines；如果它必须卡在 git 事件（PR/push）上做确定性检查，就用 Actions；如果它要跑好几个小时还带自定义 MCP，就用 Managed Agents。

本文重点覆盖前两条路径，因为它们是"把本地 Agent 经验迁移到无人值守"时成本最低、ROI 最高的两种。

flowchart TD
    A[我要自动化一个 Claude Code 任务] --> B{触发方式是什么?}
    B -->|PR/push 等确定性 git 事件| C[GitHub Actions + -p Headless]
    B -->|定时 cron / Webhook / GitHub 事件| D[Claude Code Routines]
    B -->|长时运行+持久状态+自定义MCP| E[Managed Agents]
    C --> F{是否要改代码?}
    F -->|只读审查| G[contents: read + PR 评论]
    F -->|要提交修复| H[contents: write + skip-ci]
    D --> I[云端容器: 系统/输入/输出/触发器]

第二步：Headless 模式核心参数速查

CI 场景下你几乎不会用交互式 TUI，而是用 -p（即 --print）让 Claude Code 处理单个 prompt 后立即退出。下面是 CI 中最常用的几个开关，建议把它们当作"自动化挡位盘"来记：

# 最小可用：单 prompt，纯文本输出
claude -p "总结当前仓库的目录结构"

# CI 标配：结构化 JSON 输出 + 限制工具 + 限制轮次
claude -p "审查这个 diff 的潜在 bug" \
  --output-format json \
  --allowed-tools "Read,Bash(git diff:*)" \
  --max-turns 8

# 续跑：基于上次会话继续（长任务分片）
claude -p "继续上次的迁移工作" --resume <session_id>

# 权限模式：CI 里通常用 acceptEdits 让它能自动改文件
claude -p "修复所有 lint 错误" --permission-mode acceptEdits

各参数在 CI 中的作用：

常见问题：CI 里报 Failed to enable TUI 之类错误？原因是你用了交互模式。解法就是一律加 -p。另一个高频坑是 Agent 在 CI 里无限循环——务必给 --max-turns 兜底。

第三步：GitHub Actions 自动代码审查实战

最经典、ROI 最高的 CI 集成：PR 一开/一更新，Claude Code 自动读 diff 并评论。先做三件准备工作：

1. 在仓库 Settings → Secrets and variables → Actions 里添加 ANTHROPIC_API_KEY
2. 工作流只声明最小权限：审查用 contents: read + pull-requests: write
3. actions/checkout 时设 fetch-depth: 0，让 Agent 能拿到完整 diff 上下文

最小可用的审查工作流：

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
permissions:
  contents: read
  pull-requests: write
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Run code review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(git diff origin/${{ github.base_ref }}...HEAD)
          claude -p "审查以下 diff 中的明显 bug、缺失的错误处理和潜在安全问题。\
          输出精简的发现列表；若无问题输出 'No issues found'。Diff: $DIFF" \
            --output-format json \
            --allowed-tools "Read" \
            --max-turns 8 \
            | tee review-output.json

预期结果：每次 PR 触发后，Actions 日志里出现一段 JSON，其中 result 字段是审查意见。结合 GitHub 官方的 anthropics/claude-code-action，可以把这段结果自动转成 PR review comment。

常见问题：审查跑得太慢、太贵？原因是没做 path filtering——每个 commit 都跑一遍。解法是给 on.pull_request 加 paths 过滤，只在 src/** 等关键路径变化时触发：

on:
  pull_request:
    paths:
      - 'src/**'
      - '!**/*.md'

第四步：从"审查"升级到"自愈"——PR 自动修复并提交

审查只是评论，真正省事的是让 Claude Code 直接改代码并提交回分支。这里有两个关键点：用 contents: write 权限 + --permission-mode acceptEdits，以及用 [skip ci] 防止无限循环。

name: Auto-fix linting
on:
  pull_request:
    types: [opened, synchronize]
permissions:
  contents: write
jobs:
  autofix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}
          token: ${{ secrets.GITHUB_TOKEN }}
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Fix linting errors
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "运行 'npm run lint -- --fix'，然后检查是否仍有无法自动修复的 lint 错误并列出。\
          若全部干净，输出 'All clean.'" \
            --permission-mode acceptEdits \
            --allowed-tools "Bash,Edit,Read" \
            --max-turns 15
      - name: Commit changes
        run: |
          git config user.name "claude-bot"
          git config user.email "[email protected]"
          git add -A
          git diff --staged --quiet || git commit -m "chore: auto-fix lint errors [skip ci]"
          git push

关键点解读：

• ref: ${{ github.head_ref }} 确保检出的是 PR 分支而非默认分支
• git diff --staged --quiet || 这个短路逻辑：没有改动就不提交，避免空 commit
• commit message 里的 [skip ci] 是这一步的灵魂——否则提交会再次触发本工作流，形成 Agent 自我触发的死循环

常见问题：跑了一次后发现 Claude 把不该改的文件也改了？根因是 --allowed-tools 给太宽。解法是收紧到 Bash(npm run lint:*) 这种带前缀限制的精确工具授权，只允许它跑 lint 相关命令。

第五步：定时维护任务（Scheduled Maintenance）

第三种 CI 模式价值最高却最容易被忽视：没人 push 也定时跑的"家务活"。把 on: 从 pull_request 换成 schedule 即可：

on:
  schedule:
    - cron: '0 2 * * 0'   # 每周日凌晨 2 点 UTC
  workflow_dispatch: {}    # 同时允许手动触发，方便调试

实践里最稳的几类定时任务：

注意：GitHub Actions 跑这种"静默后台任务"在规模化后有两个硬伤——CI 分钟费贵、且除了 Actions 日志没有结构化运行历史。当定时任务超过 3–5 个时，把这类持久后台任务迁到下一节的 Routines，架构会干净很多。

第六步：Claude Code Routines——2026 年 4 月的云端定时 Agent

这是本教程的"新特性主角"。Routines 是 Anthropic 在 2026 年 4 月推出的产品，把一个你已经在写的 Claude Code 会话，直接变成云端可调度的自治 Agent，无需自建 cron、无需配 Runner、无需写胶水代码。

一个 Routine 的本质是几样东西的打包：

• 一段 system prompt（你已经在写的那种）
• 一个 MCP server 列表
• 一个 触发器：cron 定时 / Webhook / GitHub 事件 / 手动 API 调用
• 输入参数
• 输出处理：写文件、开 PR、发评论、推送通知

触发器一 fire，Anthropic 就拉起一个 Claude Code 容器、加载你的 Routine、传入输入、跑到完成，最后持久化输出或通过 Webhook 暴露。下面是官方高频用法"每晚依赖升级 PR"的 Routine 定义（YAML 为示意结构）：

name: nightly-dep-bumps
trigger:
  cron: "0 3 * * *"          # 每天凌晨 3 点
  timezone: America/Los_Angeles
mcp_servers:
  - github
  - bash
model: haiku-4-5             # 分类/摘要类用便宜模型
system_prompt: |
  检查本仓库中安全的 minor/patch 依赖升级。对每个：
  1. 在新分支上应用升级
  2. 运行测试套件（npm test 或 pytest）
  3. 若测试通过，开一个带变更摘要的 PR
  4. 若测试失败，丢弃分支并记录失败
  不要做 major 版本升级，单次运行不超过 5 个包。
outputs:
  on_complete:
    post_to_slack:
      channel: "#dep-upgrades"

关键能力与限制（2026 年 4 月口径）：

一个 45 秒的摘要类 Routine 大约 $0.001 运行费 + Token；一个 15 分钟的 Routine 约 $0.02 运行费 + Token。也就是说，每天跑一次摘要类巡检，一个月运行费不到 1 块钱，主要成本在 Token。

GitHub 集成是 Routines 快速被工程团队采纳的原因：安装 Claude Code GitHub App 后，它会以 claude-code-bot[bot] 身份在 PR/issue 上行动，权限按仓库粒度授予，审计痕迹干净。一个挂在 pull_request.opened 上的 Routine 会收到 PR 的 title/body/diff/author 作为输入，可以做测试、留审查意见、提建议，甚至在授权后批准 trivial PR。

常见问题：Routine 经常跑到 2 小时上限被掐断？解法有两个——把 Routine 拆得更窄（见下文 Pattern 1），或把状态持久化到卷然后重新触发；若仍不够，迁到 Managed Agents。

第七步：CI 安全目标的写法（CI-safe Goals）

无论 Actions 还是 Routines，自动化成败的瓶颈不是 YAML，是 prompt。交互场景里你能随时澄清歧义；凌晨 3 点的 CI 任务里没人能救场。所以 CI 目标必须满足四条铁律：

1. 上下文要显式。"按 src/handlers/ 里已有的模式处理错误"是可执行的；"正确处理错误"不是。
2. 范围要精确。"审查 PR diff"很好；"审查整个代码库"会触发一次又贵又长的全量扫描。
3. 硬退出条件。"最多输出 5 条 bullet，然后停"能防住失控生成——修复类任务尤其需要。
4. 先本地试。claude -p "..." 在本地把 prompt 跑通再塞进 CI，省掉大量迭代。

flowchart LR
    P[写 CI 目标] --> Q1{上下文显式?}
    Q1 -->|否| R[重写：给出文件路径/模式名]
    Q1 -->|是| Q2{范围精确?}
    Q2 -->|否| R
    Q2 -->|是| Q3{有硬退出?}
    Q3 -->|否| R
    Q3 -->|是| Q4[本地 claude -p 跑通]
    Q4 --> S[塞进 CI / Routine]
    R --> P

经验法则：一条 Routine 只做一件事。"每晚依赖升级"是好 Routine；"每晚依赖升级 + 检查 TODO + 同步文档"是三个 Routine 假装成一个——拆开能让失败隔离、输出可读。

第八步：限流、成本与可观测性

规模化后必须正面处理两个运营问题：

限流（Rate Limits）。活跃团队在每个 PR 上都跑 Claude Code，很快撞 Anthropic API 限流。三板斧：path filtering（只在关键路径变才触发）、workflow 内 concurrency: 限并发、以及批处理。下面这段并发控制能让同一 PR 的快速连续 push 只跑最后一次：

concurrency:
  group: claude-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

成本可见性。每次调 Claude Code 都有直接 API 成本。务必在 Anthropic Console 设账单告警——一个卡在 10 分钟静默循环里的 CI 任务，成本通常是正常运行的 4–8 倍。--max-turns 是你的第一道闸。

可观测性五原则（来自 Routines 两周生产实践）：

1. 保持狭窄：一个 Routine 一件事
2. 大声失败：失败路由到专门 Slack/PagerDuty，默认模式是静默失败数周没人发现
3. 版本化 prompt：把 Routine YAML 和 prompt 提交进仓库，prompt 改动要做变更控制
4. 宽任务用便宜模型：分类/摘要/分流交给 Haiku，只有真正需要推理深度才上 Sonnet/Opus
5. 加自检：Routine 末尾让它总结自己做了什么、对比目标、标记异常

第九步：选型决策——Routines vs Managed Agents vs 自建 cron

用这张表快速对号入座，避免过度工程或选错工具：

最后一条特别重要：不是所有定时任务都需要 LLM。Routines 的正确性来自 Claude 的推理——挑该报什么、写叙事、审查正确性、分类开放式输入。如果你的"自动化"其实是确定性数据搬运，Actions 里一段普通脚本更便宜更稳。

实战案例：每周代码健康巡检 Agent（完整可运行）

把前面所有知识串成一个端到端案例：每周日凌晨，Claude Code 扫描仓库的死代码、过期文档、测试缺口和技术债，汇总成一条结构化 issue。我们给出 Routines 版本（云端）和 Actions 版本（自建）两套，按你的环境选一套即可。

方案 A：Routines 版（推荐，零运维）

name: weekly-code-health
trigger:
  cron: "0 2 * * 0"          # 每周日凌晨 2 点
  timezone: Asia/Shanghai
mcp_servers:
  - github
  - bash
model: haiku-4-5             # 巡检以分类/汇总为主，便宜模型够用
max_turns: 30
system_prompt: |
  你是代码健康巡检 Agent。对当前仓库执行以下四项检查，每项最多 3 条发现：
  1. 死代码：找出无调用方的导出函数（用 ripgrep 验证 0 引用）
  2. 过期文档：找出 /docs 下 6 个月未修改、且引用了已重命名/删除 API 的文件
  3. 测试缺口：找出 import 数 top5 但测试覆盖率为 0 的源文件
  4. 技术债：扫 TODO/FIXME/HACK 注释，列出最值得处理的 3 条
  最后输出一段 Markdown 汇总，并在结尾加一段"自检"：
  说明你检查了哪些目录、跳过了什么、为什么。
outputs:
  on_complete:
    create_github_issue:
      title: "[巡检] 周度代码健康报告 {{date}}"
      labels: ["tech-debt", "automated"]

方案 B：GitHub Actions 版（自建，可控）

name: Weekly Code Health Scan
on:
  schedule:
    - cron: '0 18 * * 6'    # UTC 周六 18:00 = 北京周日 02:00
  workflow_dispatch: {}
permissions:
  contents: read
  issues: write
jobs:
  scan:
    runs-on: ubuntu-latest
    concurrency:
      group: weekly-health
      cancel-in-progress: false
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: npm install -g @anthropic-ai/claude-code
      - name: Run health scan
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -x
          claude -p "对仓库做代码健康巡检：死代码、过期文档、测试缺口、技术债各最多 3 条。\
          末尾加自检说明。输出 Markdown。" \
            --output-format json \
            --allowed-tools "Read,Bash(rg:*),Bash(git log:*),Bash(find:*)" \
            --disallowed-tools "Edit,Write" \
            --max-turns 30 \
            2>&1 | tee scan.json

          # 从 JSON 取 result 字段，开一条 issue
          REPORT=$(jq -r '.result // .text // empty' scan.json)
          [ -z "$REPORT" ] && { echo "空报告，终止"; exit 1; }
          gh issue create \
            --title "[巡检] 周度代码健康报告 $(date +%F)" \
            --body "$REPORT" \
            --label "tech-debt,automated"

设计要点拆解：

• 只读护栏：--disallowed-tools "Edit,Write" 保证巡检绝不改代码，只产出报告
• 工具白名单带前缀：Bash(rg:*) 等只允许特定命令族，杜绝命令注入面
• --max-turns 30：给够探索深度又有上限兜底
• set -x + tee scan.json：--print 输出到 stdout，落成制品便于事后排查
• 空报告保护：[ -z "$REPORT" ] && exit 1 让"静默失败"变成可见失败
• concurrency 不取消进行中：巡检是后台任务，宁可排队也不要被中途掐

预期结果：每周日凌晨自动开一条带 tech-debt,automated 标签的 issue，正文是结构化 Markdown 报告 + 自检说明。打开 GitHub Issues 按标签筛选即可看到完整周度巡检历史。

调优路径：跑两周后，若报告噪音多，就在 prompt 里加"按团队惯例，忽略 vendor/ 和 __generated__/ 目录"这类显式排除（呼应第七步"上下文显式"铁律）。

整体工作流架构

下图把"本地 → CI → 云端"三层自动化串成一张全景：

flowchart TB
    subgraph Local[本地交互层]
        L1[claude -p 一次性调用]
        L2[本地试跑 prompt 验证]
    end
    subgraph CI[GitHub Actions 层]
        PR[PR/push 事件] --> A1[自动代码审查]
        PR --> A2[Lint 自愈 + skip-ci 提交]
        SCHED[cron schedule] --> A3[定时维护任务]
    end
    subgraph Cloud[Claude Code Routines 层]
        R1[cron 触发]
        R2[GitHub 事件触发]
        R3[Webhook/API 触发]
        R1 & R2 & R3 --> CONT[Anthropic 云端容器]
        CONT --> OUT[开 PR / 开 issue / Slack 通知]
    end
    L2 -->|prompt 成熟| CI
    L2 -->|prompt 成熟| Cloud
    A1 --> GH[GitHub 评论]
    A2 --> GIT[分支提交]
    A3 --> GH
    OUT --> GH
    style Cloud fill:#e8f5e9
    style CI fill:#fff3e0

延伸阅读

• Claude Code 官方文档 · Scheduled Tasks（code.claude.com/docs/en/scheduled-tasks）：/loop 与 cron 调度工具的权威说明
• Claude Code 官方文档 · Routines（code.claude.com/docs/en/routines）：把 Claude Code 设为自动驾驶，定义按调度/API/GitHub 触发运行的 Routine
• anthropics/claude-code-action（GitHub）：官方 GitHub Action，PR 审查/自动修复开箱即用
• Claude Code Headless 自托管完整指南（amux.io）：鉴权、成本追踪、CI/CD 模式与并行 Agent 集群

训练营适用性评估

• 适用类型：面向中高级开发者的 DevOps / 平台工程 / 研发效能 训练营；也适合企业内训中"AI 代码生产力"模块的进阶单元
• 前置基础：学员需已熟悉 Claude Code 交互用法与 GitHub Actions YAML（建议先完成 Round 1 入门与一次本地 -p 调用）
• 预计教学时长：理论 + 跟做 2.5–3 小时（其中 Routines 配置 45 分钟、Actions 实战 60 分钟、案例调优 45 分钟）
• 考核建议：让学员独立完成一个"每周自动开技术债 issue"的 Routine 或 Actions，以 issue 能否稳定产出 + 报告质量作为评分依据
• 延伸方向：可与"计划模式与任务编排""Hooks 质量门禁"两个主题组成"Agent 自动化三日进阶"课程序列

参考来源

1. Claude Code + GitHub Actions: A CI/CD Integration Guide — OpenHelm — GitHub Actions 三种集成模式（审查/自愈/定时维护）与 CI-safe 目标写法的实战指南
2. Claude Code Routines: Scheduled Cloud Automation Without the DevOps Overhead — AI Magicx — 2026 年 4 月 Routines 产品的能力、限制、定价与五个最高价值 Routine 案例
3. Claude Code Routines (2026): Schedule, Webhook, and GitHub-Triggered Agents — Claude Directory — Routines vs Managed Agents vs 自建 cron 的选型框架与 GitHub 集成细节
4. Claude Code Headless Mode: The Complete Self-Hosting Guide (2026) — amux — Headless 模式鉴权、成本追踪、CI/CD 与并行 Agent 集群的自托管全景
5. Run prompts on a schedule — Claude Code Docs — /loop 与 cron 调度工具的官方文档

[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。