claude-code-action 高级配置完全指南MCP 扩展、CI 权限、模型与工具精细化调优【免费下载链接】claude-code-action项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-action本指南基于 claude-code-action 官方文档 docs/configuration.md 编写系统讲解该 GitHub Action 的高阶配置能力如何通过claude_args与settings两个核心输入扩展 MCP 服务器、授予 CI/CD 访问权限、切换模型与限制对话轮数以及如何从废弃输入平滑迁移。读完本文你将掌握在 GitHub Actions 工作流中精细化定制 Claude Code 运行行为的完整实战方案并能理解这些配置在仓库源码中的底层实现机制。配置体系的整体脉络claude-code-action 的输入设计遵循单一入口、按需透传的原则几乎所有运行期行为都收敛到claude_args直接透传 Claude Code CLI 参数和settingsClaude Code 设置文件两个输入上二者的完整定义见仓库根目录的 action.yml。claude_argsAdditional arguments to pass directly to Claude CLI提供对 Claude Code CLI 参数的直接访问优先级高于settingssettingsClaude Code settings as JSON string or path to settings JSON file既可传内联 JSON 字符串也可传设置文件的路径additional_permissionsAdditional GitHub permissions to request (e.g., actions: read)用于扩展 Claude 可访问的 GitHub 资源。从源码看claude_args在 base-action/src/parse-sdk-options.ts 中通过shell-quote解析为 SDK 可识别的extraArgs对象并支持多个累计型 flag--allowedTools、--allowed-tools、--disallowedTools、--disallowed-tools、--mcp-config、--add-dirsettings则在 base-action/src/setup-claude-code-settings.ts 中被解析并写入~/.claude/settings.json。理解这两条路径后续所有配置项就都能对号入座。使用自定义 MCP 配置扩展 Claude 能力MCPModel Context Protocol是 Claude 接入外部工具与数据源的标准协议。claude-code-action 内置了若干 GitHub MCP 服务器你可以通过--mcp-config添加自定义服务器它们会与内置服务器合并共存。基础示例添加 Sequential Thinking 服务器- uses: anthropics/claude-code-actionv1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} claude_args: | --mcp-config {mcpServers: {sequential-thinking: {command: npx, args: [-y, modelcontextprotocol/server-sequential-thinking]}}} --allowedTools mcp__sequential-thinking__sequentialthinking # ... other inputs这里有两个要点--mcp-config接受一段 JSON 字符串结构遵循 MCP 标准的mcpServers键值定义自定义服务器的工具默认不会被自动授权必须通过--allowedTools显式声明如mcp__sequential-thinking__sequentialthinking否则 Claude 无法调用。在源码层面内置服务器与用户服务器是先合并、后统一传给 CLI的关系。src/mcp/install-mcp-server.ts 中的prepareMcpConfig()负责组装内置服务器配置如github_comment、github_ci、github_inline_comment、github等而 base-action/src/parse-sdk-options.ts 中的mergeMcpConfigs()会把用户通过多个--mcp-config传入的 JSON 字符串按mcpServers键合并若传入的是文件路径则该文件保持原样透传用户文件享有更高优先级。向 MCP 服务器传递敏感信息部分 MCP 服务器需要 API Key、Token 等敏感配置。正确做法是把配置写入一个由 GitHub Secrets 渲染生成的 JSON 文件再用--mcp-config指向该文件- name: Create MCP Config run: | cat /tmp/mcp-config.json EOF { mcpServers: { custom-api-server: { command: npx, args: [-y, example/api-server], env: { API_KEY: ${{ secrets.CUSTOM_API_KEY }}, BASE_URL: https://api.example.com } } } } EOF - uses: anthropics/claude-code-actionv1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} claude_args: | --mcp-config /tmp/mcp-config.json # ... other inputsenv字段会注入到 MCP 服务器子进程环境中使服务器在启动时即可读取密钥。注意secrets 只应在 GitHub Actions 的工作流文件仓库侧中引用绝不允许把明文密钥写进 JSON 或工作流。使用 uv 运行 Python MCP 服务器对于基于 Python、通过uv管理的 MCP 服务器需要指定服务器所在目录因为uv必须在该目录下解析项目依赖- name: Create MCP Config for Python Server run: | cat /tmp/mcp-config.json EOF { mcpServers: { my-python-server: { type: stdio, command: uv, args: [ --directory, ${{ github.workspace }}/path/to/server/, run, server_file.py ] } } } EOF - uses: anthropics/claude-code-actionv1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} claude_args: | --mcp-config /tmp/mcp-config.json --allowedTools my-python-server__tool_name # Replace tool_name with your servers tool names # ... other inputs例如你的 Python 服务器位于仓库mcp_servers/weather.py则args应写为args: [--directory, ${{ github.workspace }}/mcp_servers/, run, weather.py]type: stdio表示服务器通过标准输入输出与 Claude 通信MCP 最常见的传输方式。同时配置多个 MCP 服务器claude_args支持重复使用多个--mcp-config它们会被合并- uses: anthropics/claude-code-actionv1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} claude_args: | --mcp-config /tmp/config1.json --mcp-config /tmp/config2.json --mcp-config {mcpServers: {inline-server: {command: npx, args: [example/server]}}} # ... other inputs重要约定敏感值API Key、Token、密码一律使用 GitHub Secrets${{ secrets.SECRET_NAME }}绝不硬编码到工作流文件自定义服务器与内置服务器同名时以自定义为准即用户配置会覆盖内置配置多个--mcp-config会被合并为一个整体配置内联 JSON 的mcpServers对象会逐键合并见 base-action/src/parse-sdk-options.ts 的mergeMcpConfigs实现。为 CI/CD 集成授予额外权限默认情况下Claude 无法读取 GitHub Actions 的工作流运行信息。通过additional_permissions输入可以授予相应权限使 Claude 能够分析 CI/CD 失败原因、调试工作流问题。启用 GitHub Actions 访问的步骤为 GitHub Token 授予必要权限。使用默认GITHUB_TOKEN时在工作流顶层加入actions: readpermissions: contents: write pull-requests: write issues: write actions: read # Add this line在 action 配置中声明额外权限- uses: anthropics/claude-code-actionv1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} additional_permissions: | actions: read # ... other inputsClaude 自动获得 CI/CD 工具开启actions: read后Claude 可使用以下 MCP 工具mcp__github_ci__get_ci_status— 查看工作流运行状态mcp__github_ci__get_workflow_run_details— 获取详细的工作流运行信息mcp__github_ci__download_job_log— 下载并分析任务日志这三个工具的完整实现位于 src/mcp/github-actions-server.tsget_ci_status通过 PR 的 head SHA 拉取该分支的 workflow runs 并汇总通过/失败/待处理数量get_workflow_run_details获取指定 run 的任务与失败步骤列表download_job_log将任务日志下载到RUNNER_TEMP/github-ci-logs/目录下载设有 30 秒超时保护避免请求卡死。示例调试失败的 CI 运行name: Claude CI Helper on: issue_comment: types: [created] permissions: contents: write pull-requests: write issues: write actions: read # Required for CI access jobs: claude-ci-helper: runs-on: ubuntu-latest steps: - uses: anthropics/claude-code-actionv1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} additional_permissions: | actions: read # Now Claude can respond to claude why did the CI fail?重要说明GitHub Token 必须在工作流中拥有对应权限否则工具不可用若权限缺失Claude 会给出警告并建议补充除默认权限外additional_permissions可请求actions: readchecks: readdiscussions: read或discussions: writeworkflows: read或workflows: write标准权限contents: write、pull_requests: write、issues: write始终包含无需显式声明。从实现细节看parseAdditionalPermissions()定义于 src/github/token.ts会按行解析ADDITIONAL_PERMISSIONS环境变量与DEFAULT_PERMISSIONScontents: write、pull_requests: write、issues: write合并后作为请求 GitHub App Token 的权限声明传入测试用例见 test/parse-permissions.test.ts其中还验证了额外权限可以覆盖默认值例如contents: read会覆盖contents: write以及空行、无冒号行会被安全忽略等边界行为。另外内置的github_ci服务器在安装前会通过checkActionsReadPermission()实际探测一次 token 是否具备actions: read见 src/mcp/install-mcp-server.ts若权限不足会跳过安装并输出提示而不是让 Claude 在运行时才失败。通过 settings 输入注入自定义环境变量settings输入可以为 Claude Code 执行环境注入自定义环境变量非常适合 CI/测试场景- uses: anthropics/claude-code-actionv1 with: settings: | { env: { NODE_ENV: test, CI: true, DATABASE_URL: postgres://test:testlocalhost:5432/test_db } } # ... other inputs这些环境变量在 Claude Code 执行期间可见使它可以运行依赖特定环境配置的测试、构建或其他命令。在 base-action/src/setup-claude-code-settings.ts 的实现中settings输入会与已有的~/.claude/settings.json做浅合并用户设置优先且该函数始终强制写入enableAllProjectMcpServers: true确保项目级 MCP 服务器正常工作。限制对话轮数控制成本与时长claude_args中的--max-turns可限制 Claude 任务执行期间的最大来回交互次数适合控制成本防止对话失控为自动化工作流设置时间边界让 CI/CD 管道行为可预期。- uses: anthropics/claude-code-actionv1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} claude_args: | --max-turns 5 # Limit to 5 conversation turns # ... other inputs到达轮数上限后Claude 会优雅地停止执行。取值原则给 Claude 完成典型任务留足轮数同时避免过度消耗。在 base-action/src/parse-sdk-options.ts 中--max-turns会被解析并转换为 SDK 的maxTurns数值选项parseInt处理后传入如果同时在废弃的max_turns输入里也设置了值则claude_args中的值生效。自定义工具精细化控制 Claude 的能力边界默认情况下Claude 只具备以下能力文件操作读取、提交、编辑文件只读 git 命令评论管理创建/更新评论基础 GitHub 操作。Claude默认不能执行任意 Bash 命令。如果希望它运行特定命令如npm install、npm test必须通过claude_args显式授权提示如果仓库根目录存在.mcp.json文件Claude 会自动检测并使用其中定义的 MCP 服务器工具但这些工具仍然需要显式授权后才能被调用。- uses: anthropics/claude-code-actionv1 with: claude_args: | --allowedTools Bash(npm install),Bash(npm run test),Edit,Replace,NotebookEditCell --disallowedTools TaskOutput,KillTask # ... other inputs注意基础 GitHub 工具始终包含在内。使用--allowedTools增加额外工具包括特定 Bash 命令用--disallowedTools禁止特定工具。值得了解的实现细节base-action/src/parse-sdk-options.ts 对--allowedTools/--allowed-tools、--disallowedTools/--disallowed-tools做了兼容处理——既识别驼峰拼写也识别连字符拼写多个 flag 会累积合并、去重后统一传给 SDK它还会将来自claude_args与直接输入的工具列表合并。同时该文件对Bash(gh:*)这类含括号、竖线等 shell 元字符的授权值做了转义保护避免shell-quote解析时把Bash(gh:*)错切成Bash而意外放大权限范围。自定义模型通过claude_args指定 Claude 模型- uses: anthropics/claude-code-actionv1 with: claude_args: | --model claude-4-0-sonnet-20250805 # ... other inputs云厂商专属模型使用各自的命名格式# AWS Bedrock - uses: anthropics/claude-code-actionv1 with: use_bedrock: true claude_args: | --model anthropic.claude-4-0-sonnet-20250805-v1:0 # ... other inputs # Google Vertex AI - uses: anthropics/claude-code-actionv1 with: use_vertex: true claude_args: | --model claude-4-0-sonnet20250805 # ... other inputs选用 Bedrock / Vertex 时还需要分别设置use_bedrock/use_vertex为trueaction.yml 中默认均为falseaction 会据此把CLAUDE_CODE_USE_BEDROCK/CLAUDE_CODE_USE_VERTEX注入环境并透传对应的 AWS/GCP 凭据配置。通过 API 网关使用 1M 上下文模型当ANTHROPIC_BASE_URL指向 Anthropic 兼容的 API 网关时Claude Code 可能无法确认网关是否支持某模型原生的 1M 上下文窗口从而将会话预算限制为 200K。此时可在模型名后追加[1m]选择器显式启用支持该能力的模型包括 Claude Opus 5 和 Claude Sonnet 5的 1M 上下文窗口- uses: anthropics/claude-code-actionv1 with: claude_args: | --model claude-opus-5[1m] # ... other inputs在通过ANTHROPIC_MODEL或其他 Claude Code 模型环境变量设置模型时也使用同样的选择器。该选择器由 Claude Code 在向 provider 发送请求之前解析。action 的净化结果输出会在modelUsage字段中给出每个模型解析后的contextWindow与maxOutputTokens因此无需开启show_full_output即可看到这些限额。Claude Code Settings结构化配置选项settings输入支持以 JSON 字符串或设置文件路径两种方式提供可定制模型选择、环境变量、权限与 hooks 等行为。方式一设置文件- uses: anthropics/claude-code-actionv1 with: settings: path/to/settings.json # ... other inputs方式二内联设置- uses: anthropics/claude-code-actionv1 with: settings: | { model: claude-opus-4-1-20250805, env: { DEBUG: true, API_URL: https://api.example.com }, permissions: { allow: [Bash, Read], deny: [WebFetch] }, hooks: { PreToolUse: [{ matcher: Bash, hooks: [{ type: command, command: echo Running bash command... }] }] } } # ... other inputs设置支持 Claude Code 的全部配置选项包括model覆盖默认模型env会话环境变量permissions工具使用权限hooks工具执行前/后的钩子以及其他更多选项。注意事项enableAllProjectMcpServers设置被此 action 强制置为true以保证 MCP 服务器正常工作该行为在 base-action/src/setup-claude-code-settings.ts 中固化实现claude_args直接访问 Claude Code CLI 参数优先级高于settings建议简单配置用claude_args含 hooks 与复杂环境变量的配置用settings。从废弃输入迁移大量旧的独立输入已整合进claude_args或settings迁移对照如下旧输入新用法allowed_tools使用claude_args: --allowedTools Tool1,Tool2disallowed_tools使用claude_args: --disallowedTools Tool1,Tool2max_turns使用claude_args: --max-turns 10model使用claude_args: --model claude-4-0-sonnet-20250805claude_env使用settings中的env对象custom_instructions使用claude_args: --append-system-prompt Your instructionsmcp_config使用claude_args: --mcp-config {...}direct_prompt改用prompt输入override_prompt使用带 GitHub 上下文变量的prompt仓库对迁移做了兼容性兜底src/entrypoints/collect-inputs.ts 中的collectActionInputsPresence()会对比每个输入的实际值与其默认值判断用户是否显式设置了某个可能是废弃的输入供 action 内部识别老式用法并给出引导--append-system-prompt则由 base-action/src/parse-sdk-options.ts 组装为 SDK 的systemPromptpresetclaude_code预设 追加内容。为特殊环境提供自定义可执行文件在 Nix、自定义容器或其他包管理环境默认安装方式不可用中可以自行提供可执行文件。自定义 Claude Code 可执行文件path_to_claude_code_executable用于提供自有 Claude Code 二进制替代自动安装版本- uses: anthropics/claude-code-actionv1 with: path_to_claude_code_executable: /path/to/custom/claude # ... other inputs自定义 Bun 可执行文件path_to_bun_executable用于提供自有 Bun 运行时替代默认安装版本- uses: anthropics/claude-code-actionv1 with: path_to_bun_executable: /path/to/custom/bun # ... other inputs重要使用不兼容的版本可能导致 action 失败。请确保自定义可执行文件满足 action 的版本要求。从 action.yml 的实现看默认步骤使用oven-sh/setup-bun安装固定版本 Bunbun-version: 1.3.14一旦提供了path_to_bun_executable该步骤被跳过改为把自定义 Bun 所在目录加入PATHSetup Custom Bun Path 步骤而path_to_claude_code_executable则会通过 SDK 的pathToClaudeCodeExecutable选项直接指定运行的 Claude 二进制。实战配置建议综合以上能力一个面向 CI 调试 自定义 MCP 的典型完整配置可以这样组织name: Claude CI Debugger on: issue_comment: types: [created] permissions: contents: write pull-requests: write issues: write actions: read jobs: claude-debug: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Create MCP config with secrets run: | cat /tmp/mcp-config.json EOF { mcpServers: { my-python-server: { type: stdio, command: uv, args: [--directory, ${{ github.workspace }}/mcp_servers/, run, weather.py] } } } EOF - uses: anthropics/claude-code-actionv1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} additional_permissions: | actions: read settings: | { env: { NODE_ENV: test }, permissions: { allow: [Bash, Read, Edit], deny: [WebFetch] } } claude_args: | --mcp-config /tmp/mcp-config.json --allowedTools Bash(npm install),Bash(npm run test),Edit,my-python-server__get_weather --max-turns 15该配置同时展示了CI 权限授予actions: read、环境变量注入settings.env、工具边界控制allowedTools/permissions、轮数限制--max-turns以及自定义 MCP 服务器含 secrets 的 JSON 文件的组合用法。小结claude-code-action 的高级配置围绕claude_args、settings、additional_permissions三个输入展开前者负责 CLI 参数级定制MCP 服务器、工具白名单/黑名单、模型、轮数中者负责结构化的 Claude Code 设置环境变量、hooks、权限后者负责扩展 GitHub 资源访问。理解 action.yml 的输入定义、base-action/src/parse-sdk-options.ts 的参数解析与合并逻辑、base-action/src/setup-claude-code-settings.ts 的设置落盘机制以及 src/mcp/install-mcp-server.ts、src/mcp/github-actions-server.ts 的内置服务器装配流程即可举一反三为任意 CI/CD 场景定制出安全、可控、高效的 Claude 自动化工作流。【免费下载链接】claude-code-action项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-action创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考