Epic 周免游戏领取助手

🇨🇳 中文文档 | 🇺🇸 English

Epic 周免游戏领取助手 面向普通用户，默认运行在 GitHub Actions 上。你不需要服务器，不需要本地常驻环境，也不用额外部署；只要有 GitHub 账号，按文档完成配置后就可以开始使用。

这个项目最核心的特点很直接：完全免费。

本项目基于社区开源方案持续完善，并接入了国产 GLM 多模态模型。项目核心目标是保障自动登录、验证码识别及结账流程的稳定性。相比配合 Gemini，配置 GLM 模型流程更简便，且免费额度足以满足日常自动运行需求。

如果你选择 GLM 路线，请先确认对应智谱账号已经完成实名认证，否则通常无法正常使用 API。

2026.4.28: 部分朋友反馈，不实名认证也能调用API，所以如出现无法使用的情况，请检查该项。

还没有智谱账号的话，可以通过这个邀请链接注册：BigModel.cn 邀请注册链接。

社区交流与反馈欢迎前往：LINUX DO。

如果你已经成功跑通，也欢迎来这里留言打卡：🎉 成功反馈 / Success Stories。

如果你遇到报错，也欢迎直接提 Issue。当然，是否继续使用完全由你决定；但如果你愿意留下反馈，而不是直接删库放弃，这些真实问题和使用体验，都会帮助这个项目继续改进，也会成为我们一起把它做得更稳的动力。

推荐优先使用 GLM 路线，主要优势如下：

• 配置更少：主要只要设置 GLM_API_KEY 和 GLM_MODEL。
• 成本更低：glm-4.6v 的免费额度通常足够覆盖周免领取场景。
• 更稳：glm-4.6v-flash 在高峰期偶尔会报“该模型当前访问量过大，请您稍后重试”，建议直接使用 glm-4.6v。
• 对国内用户更友好：不需要先解决 Google AI Studio 注册和可用性问题。
• 能力已验证：登录验证码、checkout 二次验证、拖拽/点选/多选题都能正常处理。

• Epic 账号邮箱与密码（用于登录）。
• 关闭 Epic 账号 2FA（邮箱/短信/验证器）。
• 注册 GLM 并准备 GLM_API_KEY（用于验证码识别）。

基础配置与运行流程如下：

Fork 之后先打开自己仓库的 Actions 页面，进入 Epic Awesome Gamer (Scheduled) 并点一次 Enable workflow，否则 GitHub 不会让这个 Fork 的定时 schedule 自动生效。

• Fork 到自己的 GitHub 账号。
• 打开 Actions，启用工作流 Epic Awesome Gamer (Scheduled)。

进入 Settings -> Secrets and variables -> Actions。

必须配置：

如果你使用 GLM，建议先按下面这组填写：

如果你使用 GLM_API_KEY，请先确认对应智谱账号已经完成实名认证，否则 API 很可能不可用。

配置页面示例：

如果你使用 Gemini 官方接口，请按下面这组填写：

如果你使用 AiHubMix 这类 Gemini 兼容中转接口，请按下面这组填写：

说明：

• 当前代码同时支持 Gemini 官方接口 和 AiHubMix 这类 Gemini 兼容接口。
• 变量名是 GEMINI_BASE_URL，不是 GEMINI_BASE_MODEL。
• 使用 Gemini 官方接口 时，GEMINI_BASE_URL 应留空，让 SDK 直接走 Google 官方默认地址。
• 使用 AiHubMix 或其他 Gemini 兼容中转接口时，再填写对应的 GEMINI_BASE_URL。
• 对 GLM 路线，推荐把 GLM_MODEL 设为 glm-4.6v；glm-4.6v-flash 在高峰期可能报“该模型当前访问量过大，请您稍后重试”。
• 对 Gemini / AiHubMix 路线，建议先用 GEMINI_MODEL=gemini-2.5-pro 作为起步配置。
• CHALLENGE_CLASSIFIER_MODEL、IMAGE_CLASSIFIER_MODEL、SPATIAL_POINT_REASONER_MODEL、SPATIAL_PATH_REASONER_MODEL 如果留空，会自动跟随当前 provider 的默认模型，也就是 GLM_MODEL 或 GEMINI_MODEL。
• 如果你暂时不想细分模型，最简单的做法就是让上面 4 个覆盖项全部留空。
• 走 GLM 路线时不需要额外再填 GEMINI_API_KEY。

如果你确实要单独覆盖这 4 个模型，可以直接照下面填写：

• 进入 Actions 页面。
• 选择 Epic Awesome Gamer (Scheduled)。
• 点击 Run workflow。

成功时日志通常会出现类似内容：

Login success
Right account validation success
Authentication completed
Starting free games collection process
All week-free games are already in the library

示例日志（中间有报错但最终成功）：

如果你在日志里看到多次重试后手动取消，像下面这样；请你下一次运行时多给它一些耐心，有些脚本通常运行15min至20min才成功：

每次 GitHub Actions 运行结束后，工作流会尝试上传下面这些 artifact。GitHub 只会显示实际有文件的 artifact，所以不同用户可能只看到其中一部分，这是正常现象。

| Artifact | 内容 | 通常什么时候出现 | | --- | --- | | epic-logs-<run_id> | 运行日志 | 基本每次运行都会有 | | epic-runtime-<run_id> | promotions.json、purchase_debug 截图和文本 | 已进入周免领取、商品页或 checkout 阶段时常见 | | epic-screenshots-<run_id> | 登录失败、风控页、授权页等额外截图 | 登录、风控或授权阶段保存过截图时才会有 |

下载位置：

1. 进入本次 Actions 运行页面
2. 拉到页面底部
3. 找到 Artifacts
4. 下载 zip 文件

说明：

这些内容是 GitHub Actions 每次运行后打包上传的产物，不是仓库根目录里预置好的固定目录。

如果你要提 issue，请不要只粘贴一小段日志。最有用的做法是：

1. 打开出问题的 GitHub Actions 运行页面。
2. 拉到页面底部，找到 Artifacts。
3. 下载页面中实际出现的 artifact：
   • epic-logs-<run_id>.zip：优先下载，通常每次都有
   • epic-runtime-<run_id>.zip：如果页面中有这个包就下载
   • epic-screenshots-<run_id>.zip：如果页面中有这个包就下载
4. 新建 issue。
5. 把这些 zip 直接拖进 issue 编辑框，或者点击附件按钮上传。

这些 zip 里通常已经包含定位问题所需的完整日志、截图和 purchase_debug 文本。GitHub issue 支持直接上传 .zip 文件。

补充说明：

• 如果你的 fork 是公开仓库，通常附上本次 Actions 运行链接即可，维护者一般可以直接查看对应页面。
• 如果你的 fork 是私有仓库，请务必上传本次运行实际出现的 artifact zip；维护者无法直接访问私有仓库的 Actions 页面和运行产物。

如果你想在本地复现和 GitHub Actions 相同的入口，可以直接用仓库内置单次执行方式：

1. 复制 .env.example 为 .env
2. 填好你自己的账号和模型配置
3. 执行 uv sync --group dev
4. 执行 ENABLE_APSCHEDULER=false uv run app/deploy.py

.env、.venv、app/volumes/ 都已经被 .gitignore 忽略，不会被提交到 GitHub。

原因：GitHub Actions 环境采用公共 IP，易触发 Epic 严格风控，导致验证码成功率波动，属预期内现象。

这通常不是模型接口问题，而是 Epic 账号状态问题。某些账号在登录成功后，会被额外重定向到类似 /id/login/correction/privacy-policy 的页面，要求先确认一次隐私政策。

处理方式很简单：先在你自己的正常浏览器里手动登录 Epic，完成这个确认页，然后再重新运行 Actions。

这说明 Epic 账号的二步验证还没有关闭。当前项目不支持处理 Epic 的邮箱 / 短信 / 验证器二步验证，所以这类情况需要先在 Epic 账号设置里手动关闭，再重新运行。

如果你看到下面这些信号，通常都可以按“2FA 没关”处理：

• errors.com.epicgames.common.two_factor_authentication.required
• Two-Factor authentication required to process request
• 页面跳转到 /id/login/mfa

处理方式：

1. 在你自己的正常浏览器里登录 Epic 账号
2. 进入账号安全设置页面
3. 把当前启用的验证方式全部点 Remove
4. 确认邮箱验证、短信验证、验证器等二步验证都已关闭
5. 重新运行 Actions

参考界面如下：

这不是异常，是 Epic 结账阶段追加的人机校验。

说明：此为 Epic 结账阶段追加的安全校验机制。项目已适配该环节的自动化处理逻辑，出现这类弹窗不代表脚本已经失效。

这个提示通常出现在商品只支持 Windows，而 GitHub Actions 运行环境是 Linux 的时候。

它本身不一定代表领取失败。当前脚本会尝试自动点击弹窗里的 Continue 继续进入后续流程。

过去常见根因有：

如果你不想用 GitHub Actions，也可以在自己的服务器、NAS 或本地 Docker 环境里跑。

git clone https://github.com/Ronchy2000/epic-freebies-helper.git
cd epic-freebies-helper

主要入口是 docker/docker-compose.yaml。

GLM 示例：

environment:
  - LLM_PROVIDER=glm
  - GLM_API_KEY=your_glm_key
  - GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
  - GLM_MODEL=glm-4.6v

Gemini 官方接口示例：

environment:
  - LLM_PROVIDER=gemini
  - GEMINI_API_KEY=your_gemini_key
  - GEMINI_BASE_URL=
  - GEMINI_MODEL=gemini-2.5-pro

AiHubMix 示例：

environment:
  - LLM_PROVIDER=gemini
  - GEMINI_API_KEY=your_key
  - GEMINI_BASE_URL=https://aihubmix.com
  - GEMINI_MODEL=gemini-2.5-pro

docker compose up -d --build

如果你想看项目结构、适配细节、开发者排障记录和这次踩过的坑，请继续阅读：

• 开发者进阶文档
• Advanced Guide (English)
• 维护日志

本项目基于 QIN2DIM/epic-awesome-gamer 实现，并参考了 10000ge10000/epic-kiosk：

感谢原作者、维护者和社区的长期积累。

• 本项目仅用于学习和研究自动化流程。
• 自动化操作可能违反相关平台的服务条款，请自行评估风险。
• 使用本项目产生的后果由使用者自行承担。

本项目的持续完善，离不开每一位在遇到报错时没有选择放弃，而是耐心回传完整错误现场的使用者。

许多边界情况的修复，并非源自开发者的独自排查，而是建立在大家主动提供的详实日志、截图与复现步骤之上。正是这些真实的报错数据，让各种隐蔽的问题得以被精准定位并解决。

在此，向所有提供过反馈的用户致以由衷的感谢。是你们投入的时间与提供的测试数据，逐步扫除了开发过程中的盲区，让这个项目日益稳定，切实帮助到了更多人。