---
title: "Claude 集成与使用指南"
status: summer
created: 2025-08-17
owner: Claude
review_by: "2026-02-17"
tags: ["guide", "claude", "core"]
---

# Claude 集成与使用指南

本指南介绍如何在炼妖壶项目中使用 Claude，包括运行时模型接入、GitHub 代码审查助手（可选）以及常见问题排查。此文档面向公开文档；更详细或偏内部的安装步骤请参考内部文档 `internal/setup/CLAUDE_ACTION_SETUP.md`。

## 适用场景

- 在项目中调用 Claude 模型（通过 LiteLLM/OpenRouter/Anthropic）用于分析、辩论与推理
- 在 GitHub 的 Issue/PR 中通过评论触发 Claude 进行代码审查、调试辅助与架构讨论（可选）

## 快速开始（运行时模型）

项目推荐通过 LiteLLM 路由到不同模型供应商。你可以选择两种常见方式接入 Claude：

- 方式 A：使用 OpenRouter 免费路由（如 `anthropic/claude-3.5-sonnet:free`）
- 方式 B：直接使用 Anthropic 官方 API（需要付费 API Key）

### 环境变量

至少准备以下中的一个或多个（按你的接入方式选择）：

- OPENROUTER_API_KEY: 使用 OpenRouter 路由时需要
- ANTHROPIC_API_KEY: 直接调用 Anthropic API 时需要

建议将密钥保存到本地 `.env` 或 CI/CD 的 Secret 中，不要提交到仓库。

### LiteLLM 配置提示

仓库中 `litellm/config.yaml` 是示例配置。你可以添加 Claude 相关配置，例如：

```yaml
model_list:
  - model_name: claude-free
    litellm_params:
      model: anthropic/claude-3.5-sonnet:free
      # 如果使用 OpenRouter，请在运行环境里提供 OPENROUTER_API_KEY

  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-3-5-sonnet-20240620
      # 如果直接使用 Anthropic 官方，请在运行环境里提供 ANTHROPIC_API_KEY
```

> 提示：内部文档 `internal/technical/Sanqing_Baxian_OpenRouter_Model_Assignment.md` 与 `internal/technical/Final_Baxian_Sanqing_Model_Configuration.md` 描述了项目在三清八仙体系中对 Claude 的模型分配建议，可作为策略参考。

## GitHub 助手（可选）

如果你希望在 GitHub 的 Issue/PR 评论中 @Claude 进行协助，请按以下步骤配置。若当前仓库没有工作流文件，请根据下面示例新建。

1) 在 GitHub 仓库设置中添加 Secret（任选一种或两种）：
- ANTHROPIC_API_KEY: 你的 Anthropic API Key
- CLAUDE_CODE_OAUTH_TOKEN: Claude Code OAuth Token（Pro/Max）

2) 安装 Claude GitHub App（如果还未安装）
- 访问 https://github.com/apps/claude
- 选择安装到你的仓库并授权必要权限

3) 新建或更新工作流文件 `.github/workflows/claude.yml`

```yaml
name: Claude Assistant

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  run-claude:
    if: contains(github.event.comment.body, '@claude') || contains(github.event.comment.body, '@太公') || contains(github.event.comment.body, '@八仙')
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      pull-requests: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install deps
        run: |
          python -m pip install --upgrade pip
          pip install litellm

      - name: Run Claude reply
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          python - <<'PY'
          import os, json, requests

          body = os.environ.get('GITHUB_EVENT_PATH')
          import sys, pathlib
          event = json.load(open(os.environ['GITHUB_EVENT_PATH']))
          comment_body = event['comment']['body']
          issue_url = event['issue']['comments_url'] if 'issue' in event else event['pull_request']['comments_url']

          if '@claude' in comment_body or '@太公' in comment_body or '@八仙' in comment_body:
              prompt = comment_body.replace('@claude','').replace('@太公','').replace('@八仙','').strip()
          else:
              sys.exit(0)

          # 调用 Claude（示例：通过 LiteLLM 统一调用，环境里准备好 API Key）
          import litellm
          litellm.set_verbose(False)
          resp = litellm.completion(model="anthropic/claude-3.5-sonnet:free", messages=[{"role":"user","content":prompt}])
          text = resp.choices[0].message.get('content') if hasattr(resp.choices[0], 'message') else resp['choices'][0]['message']['content']

          headers = {"Authorization": f"Bearer {os.environ['GITHUB_TOKEN']}", "Accept": "application/vnd.github+json"}
          requests.post(issue_url, headers=headers, json={"body": text})
          PY
```

- 触发词默认支持：`@claude`、`@太公`、`@八仙`
- 你可以在工作流的 `if:` 条件中添加更多触发词

> 注意：内部文档 `internal/setup/CLAUDE_ACTION_SETUP.md` 提供了更完整的 Action 版配置与触发词说明。

## 使用示例

- 代码审查：
  - 在 PR 评论中输入：`@claude 请审查这个MCP管理器的实现，关注安全性和性能`
- 功能实现建议：
  - 在 Issue 评论中输入：`@claude 帮我实现一个新的Yahoo Finance数据获取功能`
- 架构讨论：
  - 在评论中输入：`@太公 如何优化当前的金融数据分析流程？`
- 调试帮助：
  - 在评论中输入：`@八仙 这个错误是什么原因：[粘贴错误信息]`

## 成本与安全

- API 成本：使用 Anthropic 直连会产生费用；OpenRouter 免费路由有速率与配额限制
- 权限：GitHub App 与工作流权限请最小化配置
- 敏感信息：不要在公开评论中包含敏感数据；密钥请使用 Secret 管理

## 常见问题排查

- 无法调用成功：确认已在运行环境设置了相应的 API Key（`OPENROUTER_API_KEY` 或 `ANTHROPIC_API_KEY`）
- 工作流未触发：确认评论中包含触发词，且仓库已启用 `Actions`；检查 `if:` 条件
- 响应为空或报错：降低请求长度，检查模型名称是否正确，或改用其他可用模型

## 参考

- 内部：`internal/setup/CLAUDE_ACTION_SETUP.md`
- 内部：`internal/technical/Final_Baxian_Sanqing_Model_Configuration.md`
- 内部：`internal/technical/Sanqing_Baxian_OpenRouter_Model_Assignment.md`