# Universal Modder 怎么用：安装命令、素材费用和常见报错

> Universal Modder 是装进 Claude Code、Codex 的免费开源 mod 工具包：装好后选单机游戏、备份存档、先做一个小功能；自动测试仅限 Windows/WSL。

- Source: https://www.aifreeapi.com/zh/posts/universal-modder
- Language: zh
- Published: 2026-10-08
- Updated: 2026-10-08
- Publisher: AI Free API (https://www.aifreeapi.com)

Universal Modder 不是一个双击打开、点几下就能改游戏的软件。它是一套装进编程智能体里的开源工具包（MIT 许可），包括一组智能体技能文件、一个叫 `um` 的命令行工具、一份连接 fal 素材生成服务的 MCP 配置，以及一个由各路智能体写下的游戏改造笔记库。你在 Claude Code、Codex 这类智能体里用中文说"给某个游戏加个什么"，智能体按它的流程去识别引擎、读代码、写 mod、生成贴图和音效，再启动游戏验证。

用法可以压成三步：

1. 按你手上的智能体运行对应的安装命令，并装好 Git、Python 3.10+ 和 ffmpeg；
2. 在一个空的工作文件夹里启动智能体，调用 `mod-any-game` 技能（Claude Code 里是 `/universal-modder:mod-any-game`），说清楚游戏、想加的东西和"做成"的标准；
3. 让它先备份存档、只做一个能跑通的小功能，最后你在游戏里亲眼看到效果才算完成。

几个前提先说清：工具免费，但你得有一个能用的编程智能体（通常要付订阅或按量付费）；生成贴图、音效、3D 模型走 fal 的付费 API，不想花这笔钱可以接本地 ComfyUI；智能体自动启动游戏、截图、录屏只支持 Windows 原生或 WSL；联网且有反作弊的游戏、你没有正版的游戏，它会直接拒绝。截至 2026 年 10 月 8 日，项目在 GitHub 上约 5,400 星，版本号 0.2.0，还没有正式发版，命令和技能文件几乎每天都在改，下面的命令以 [GitHub README](https://github.com/rehan-remade/universal-modder#install) 的写法为准。

## 开工前的四项判断：智能体、系统、游戏、预算

| 先问自己 | 可以直接开始 | 需要先处理，或换个目标 |
| --- | --- | --- |
| 手上有哪个编程智能体 | 已经在用 Claude Code、Codex、Cursor、VS Code Copilot 或 OpenCode | 一个都没有：先选一个并解决付费；Gemini CLI 个人账号的"使用 Google 登录"已在 2026 年 6 月 18 日停用 |
| 电脑系统 | Windows 10/11，或 Windows 上的 WSL | macOS、Linux：扫描、知识库、素材工具能用，但 `um win` 会拒绝运行，进游戏测试要你自己来 |
| 想改的游戏 | 你拥有正版的单机或离线游戏，最好有成熟加载器：Terraria（tModLoader）、星露谷物语（SMAPI）、Minecraft（Fabric）、Unity 游戏（BepInEx） | 联网且有反作弊（EasyAntiCheat、BattlEye、Vanguard、官方服的 VAC 等），或不是你自己的游戏：工具会拒绝 |
| 预算 | 工具免费；先用占位图做功能，素材最后再生成 | 想要大量高质量精灵图、3D 模型或视频：开工前先算 fal 费用 |

**智能体怎么选。** Universal Modder 对各家智能体给的是同一套技能和同一个 `um` 工具，差别在智能体本身的付费方式和额度。Claude Code 需要 Claude 的 Pro、Max、Team、Enterprise 订阅，或开通 API 计费的 Console 账号；Codex 走 ChatGPT 套餐额度或 API。知识库里留下改造笔记的作者既有 Claude Code，也有 Codex 和接 DeepSeek 模型的 OpenCode，并不限定某一家。两者的取舍见 [Claude Code vs Codex 2026：现在该选哪个编程智能体？](/zh/posts/claude-code-vs-codex)；完全没接触过 Claude Code 的话，先看 [Claude Code 是什么：能做什么、在哪用、怎么收费](/zh/posts/what-is-claude-code)。

**不会写代码能不能用。** 代码由智能体写，你不需要自己写。但你得会在终端里粘贴命令、安装几个依赖，并看懂智能体问你的问题，比如"要不要往游戏目录装加载器""能不能接管鼠标键盘"。最后在游戏里确认效果的也是你。

**macOS 的边界。** `um win`（启动游戏、截图、模拟输入、录屏）在代码里写死了只在 Windows 原生或 WSL 下运行，在 macOS 上会提示改用系统截图和 ffmpeg 自己处理。所以在 Mac 上可以让智能体做侦察、查知识库、写代码、生成素材，但"自动进游戏测一遍"这一环得你手动完成。知识库里也有人在 macOS 上通过 Wine 跑通过改造，只是不属于默认流程。

## 安装命令：按你用的智能体选一行

每种安装方式拿到的是同一套技能、fal MCP 服务和 `um` 工具。截至 2026 年 10 月 8 日，README 给出的命令如下：

| 智能体 | 怎么装 |
| --- | --- |
| Claude Code | 在 Claude Code 对话框里先输入 `/plugin marketplace add rehan-remade/universal-modder`，再输入 `/plugin install universal-modder@universal-modder` |
| Codex | 在终端运行 `codex plugin marketplace add rehan-remade/universal-modder`，再运行 `codex plugin add universal-modder@universal-modder` |
| Gemini CLI | 在终端运行 `gemini extensions install https://github.com/rehan-remade/universal-modder` |
| VS Code / Copilot | 打开设置项 `chat.plugins.enabled`，运行 **Chat: Install Plugin From Source**，填入仓库地址 |
| Cursor | 从 Cursor Marketplace 安装，或克隆仓库后在仓库目录里打开 |
| OpenCode | 克隆仓库，在仓库目录里运行 `opencode` |
| 其他支持 Agent Skills 的智能体 | `npx skills add https://github.com/rehan-remade/universal-modder`（只装技能文件） |
| 以上都不是 | `git clone https://github.com/rehan-remade/universal-modder`，在仓库目录里启动你的智能体 |

插件安装和克隆仓库都会把 `um` 放进 PATH。只装了技能文件，或者想在别处单独用 `um`，再装一次命令行工具：

```bash
uv tool install git+https://github.com/rehan-remade/universal-modder
# 没有 uv 时：pipx install git+https://github.com/rehan-remade/universal-modder
```

### 依赖：Git、Python 3.10+、ffmpeg 和 fal 密钥

README 列出的必需项是 Git、Python 3.10 或更高版本、ffmpeg，推荐装 uv；Blender 只在把 3D 模型渲染成精灵图时才需要。Windows 上可以用 winget 一次装好（Python、uv、ffmpeg 的包名取自 VGTimes 的安装教程）：

```powershell
winget install --id Git.Git -e
winget install Python.Python.3.12
winget install astral-sh.uv
winget install Gyan.FFmpeg
```

装完关掉终端重新打开，依次运行 `git --version`、`python --version`、`uv --version`、`ffmpeg -version`，都能输出版本号再继续。

素材生成要一个 [fal API 密钥](https://fal.ai/dashboard/keys)，fal MCP 服务和 `um fal` 都靠它：

```powershell
# Windows：写入用户环境变量，然后重开终端
setx FAL_KEY "你的 fal 密钥"
```

```bash
# macOS / Linux / WSL：写进 ~/.zshrc 或 ~/.bashrc
export FAL_KEY="你的 fal 密钥"
```

据 VGTimes 的教程，`um` 也能读取项目文件夹里的 `.env`，但 Claude Code 里的 fal MCP 服务只认环境变量，所以直接设环境变量最省事。密钥不要贴进对话，也不要提交进 mod 仓库。暂时没有 fal 账户也能开工：第一个功能用占位图就够，没有密钥时 `um comfy` 可以调用本机的 ComfyUI 出图。

### Claude Code：装好后用 /universal-modder:mod-any-game 调用

先在 Windows 上装好 Claude Code（方法见 [Windows 安装 Claude Code：原生安装器、WinGet、WSL 三种方法与国内使用](/zh/posts/claude-code-windows-install)），再按下面的顺序走：

1. 建一个专门放 mod 的文件夹，比如 `C:\mods`，在这里打开终端运行 `claude`，首次启动时选择信任该文件夹；
2. 输入上面两条 `/plugin` 命令。安装时会让你选范围：选 User 表示在这台电脑的所有项目里都启用；
3. 如果提示需要重新加载，运行 `/reload-plugins`；
4. 运行 `/plugin` 查看已安装列表里有没有 universal-modder，再让它执行一次 `um --version`，能输出版本号就说明插件和命令行工具都到位了。

调用主技能的写法是插件名加技能名：`/universal-modder:mod-any-game`，后面直接接你的需求。也可以不写这个前缀、直接用中文描述，Claude Code 会自己判断要不要调用技能；想确保它按 Universal Modder 的流程走（先侦察、先备份、进游戏验证），就显式写出来。

有两点和日常用 Claude Code 不同。第一，[Claude Code 插件文档](https://code.claude.com/docs/en/plugins)说明，启用的插件即使这一轮没用到，技能名称和描述也会每轮占用上下文和用量；不改游戏的时候，用 `/plugin` 或在终端运行 `claude plugin disable` 把它停用。第二，插件以你的用户权限运行代码，而浏览器里的 claude.ai/code 云端会话不加载本机插件，改本机游戏只能在本地终端、桌面应用的本地会话或 VS Code 扩展里做。

### Codex、Gemini CLI 和本地模型

**Codex。** 在终端运行上表的两条 `codex plugin` 命令，然后进入工作文件夹运行 `codex`，在需求里写明"用 mod-any-game 技能"。改游戏需要启动游戏进程、读写游戏目录和存档目录，这些都在工作区之外，Codex 会按沙箱和批准设置停下来问你；该放到什么程度，见 [Codex 沙箱与 config.toml：权限、批准和网络怎么配](/zh/posts/codex-config-toml)。

**Gemini CLI。** README 仍然列着它，但 [Google 的停用说明](https://developers.google.com/gemini-code-assist/docs/deprecations/code-assist-individuals)写明：从 2026 年 6 月 18 日起，Gemini Code Assist 个人版、Google AI Pro、Google AI Ultra 账号不能再用"使用 Google 登录"访问 Gemini CLI，Standard 和 Enterprise 订阅不受影响。只有你现有的认证方式还能用时，这条路才走得通，详情见 [Gemini CLI 还能用吗？个人账号停服范围与迁移指南](/zh/posts/gemini-cli-deprecated)。

**本地模型。** 维护者在 issue 里说明，测试过的本地路线是 OpenCode 接 LM Studio 的本地服务器；LM Studio 自带的 Bionic 智能体"应该大体能用"但没测过，而且效果很看模型本身。

## 国内使用：订阅、GitHub 网络和按量计费的 Codex 路线

在中国大陆用这套工具，卡点通常有三处。

**GitHub 访问。** 上面每一种安装方式，`/plugin marketplace add`、`codex plugin`、`git clone`、`uv tool install git+...`，都要从 GitHub 拉代码。安装报克隆失败或超时，先在同一个终端运行 `git ls-remote https://github.com/rehan-remade/universal-modder`，能列出分支再回去装；这一步不通，就是网络问题而不是插件问题。

**智能体订阅。** Claude 和 ChatGPT 的订阅在国内都不容易直接买到。如果你买不到订阅、又想用 Universal Modder，可以让 Codex 走按 token 计费的第三方 API。以 laozhang.ai 为例，它的 [Codex CLI 接入文档](https://docs.laozhang.ai/scenarios/programming/codex-cli)（文档标注适用于 Codex CLI 0.160.0，更新日期 2026 年 10 月 5 日）给的配置是：先把密钥写进环境变量 `LAOZHANG_API_KEY`，再在 `~/.codex/config.toml` 写入：

```toml
model = "gpt-6-sol"
model_provider = "laozhang"

[model_providers.laozhang]
name = "LaoZhang API"
base_url = "https://api.laozhang.ai/v1"
env_key = "LAOZHANG_API_KEY"
wire_api = "responses"
```

运行 `codex exec --skip-git-repo-check "Reply with exactly one word: connected"`，输出 `connected` 就说明连通了，之后按上一节装插件即可。选这条路之前要清楚三件事：它按 token 计费，同一份文档提醒一次 Codex 任务可能消耗几十万 tokens，而改游戏要反复侦察、反编译、测试，做一个 mod 要多少 token 没有公开的实测数据；这里用的是 GPT 系列模型，不是 Claude；这些模型在逆向游戏代码这类任务上的效果也没有公开对比。建议给密钥设好额度，先做一个最小的功能看看实际花费。Codex 接第三方 API 的通用注意事项见 [Codex 接第三方模型 API：先确认 Responses 兼容，再写 provider](/zh/posts/codex-third-party-api)。

**fal 付费。** 素材生成要给 fal 账户充值。如果暂时不方便，先跳过：第一个 mod 的功能用占位图验证，贴图交给本机 ComfyUI（`um comfy`），或者自己画。

## 第一个离线 Mod：五步走到游戏里看见效果

下面用 Terraria 举例。它没有反作弊，tModLoader 在 Steam 上免费提供，知识库里也已经有这款游戏的笔记，适合当第一个目标。换成别的游戏，流程一样，用到的加载器不同。

![第一个 Mod 选游戏的判断流程：没有正版会被拒绝，联网反作弊客户端改走离线模式或官方工具，有 tModLoader、SMAPI、Fabric、BepInEx 等成熟加载器的游戏适合当第一个目标](https://www.aifreeapi.com/posts/zh/universal-modder/img/first-game-check.webp)

### 第 1 步：备好正版游戏和工作文件夹

确认 Terraria 已在 Steam 上购买并安装。到 Steam 商店把免费的 tModLoader 加进库里，手动启动一次让它建好文件夹，再关掉。tModLoader 会检查这一项，没有就不启动，Universal Modder 也不会替你绕过这个检查。然后新建一个项目文件夹，比如 `C:\mods\terraria-first`，在里面打开终端启动智能体。

### 第 2 步：用一句话说需求，并说清"做成"是什么样

需求越具体，智能体追问越少。可以这样写：

```text
/universal-modder:mod-any-game 我在 Steam 上有 Terraria，想做一个单机 mod：
加一把新剑，挥砍时射出一道会追踪最近敌人的光弹。
先用占位贴图，只做这一把剑。做成的标准：在测试世界里能合成或拿到这把剑，
砍出光弹并追踪敌人，给我看日志和截图。暂时不需要展示视频。
```

技能默认把"做成"定义为游戏里能用、再加一段 20–45 秒的展示视频；不需要视频就在开头说明。智能体会在工作文件夹里建一个 `MODLOG.md` 工作日志，记录路径、类名、失败原因和下一步。

### 第 3 步：让它先侦察，你确认路线

智能体会先运行 `um kb search "terraria"` 查知识库里有没有前人的笔记，再用 `um scan --list` 找出本机装了哪些游戏、`um scan "terraria"` 识别引擎、版本、反作弊、已装的加载器和存档位置，最后按"能达到目标的最便宜路线"选方案：只改数据文件、调用加载器接口、给托管代码打补丁、原生 hook、重写，难度依次升高。Terraria 这种有 tModLoader 的游戏会走加载器接口。

它往游戏目录装加载器、接管鼠标键盘、改注册表或画面设置、删除任何东西之前都会先问你。这时看一眼它写进 `MODLOG.md` 的路线和理由再点同意。

### 第 4 步：备份存档，开一个测试专用存档目录

第一次带 mod 启动游戏前，智能体应该先运行：

```powershell
um backup create "<um scan 给出的存档目录>" --name terraria-saves
```

`um backup` 还有 `diff` 和 `restore`，恢复方法会写进 `MODLOG.md`；具体参数用 `um backup --help` 查。Terraria 这边还会用 tModLoader 的 `-tmlsavedirectory` 参数另开一个测试存档目录，你的真实角色和世界不会被碰到。它还会把游戏切到固定大小的窗口模式，好让截图和点击坐标稳定。

### 第 5 步：先做一个小功能，在游戏里亲眼看到

技能要求先把一件物品从定义、加载到游戏里生效完整跑通，再往外扩。验证靠两样东西：游戏日志和它自己看过的截图。常见日志位置：

| 游戏或加载器 | 日志文件 |
| --- | --- |
| tModLoader | `client.log` |
| BepInEx | `BepInEx/LogOutput.log` |
| UE4SS | `UE4SS.log` |
| Unity | `AppData/LocalLow/<公司名>/<游戏名>/` 下的 `Player.log` |
| Minecraft | `logs/latest.log` |

智能体自动操作游戏时别碰鼠标键盘，多一次点击就会打乱它的坐标。同一个错误连续出现 3 次，技能规定它停下来，把已知情况写进日志，换方法或来问你。

等它报告完成，你自己进测试世界试一遍：剑能拿到、光弹能射出、会追踪敌人，这个 mod 才算做成。只看到"编译成功"或"代码已写好"不算。

做成之后再往上加：用 `um fal` 生成正式贴图和音效（下一节先算钱）；需要展示视频就让它录 20–45 秒；准备分享时运行 `um publish check <mod 文件夹> --game "<游戏安装目录>"`，它会拦下游戏原文件、反编译代码和泄露的密钥。项目要做好几天的话，第二天在同一个文件夹开新会话，让它"先读 MODLOG.md 再继续"。

## 素材费用怎么算：fal 单价 × 张数，默认精灵图每张 $0.211

工具本身不收钱，花钱的是两部分：智能体本身的订阅或 API 用量，以及 fal 的素材生成。前者没有"做一个 mod 多少钱"的公开实测，长时间侦察、反编译、反复测试很容易撞上套餐限额，相关说明见 [Claude Max 和 Pro 限额差在哪？5x、20x 升级后仍有周上限](/zh/posts/claude-code-pricing-pro-vs-max)、[Claude Code 速率限制与额度：5 小时窗口、周限额，用完怎么办](/zh/posts/claude-code-rate-limit) 和 [Codex 报 429 并停止重试：先找限流归属，再恢复任务](/zh/posts/codex-rate-limits)。后者可以按单价提前算出来。

`um fal` 各配方的默认模型写在 [um/fal.py](https://github.com/rehan-remade/universal-modder/blob/main/um/fal.py) 里，截至 2026 年 10 月 8 日 fal 模型页上的标价如下（fal 的价格，不是 OpenAI 或 Google 的直连价）：

| 配方 | 默认模型 | fal 标价 |
| --- | --- | --- |
| `um fal sprite` 透明背景精灵图 | `openai/gpt-image-2`，默认高质量、1024×1024 | 每张高质量 $0.211，中等 $0.053，低 $0.006（[模型页](https://fal.ai/models/openai/gpt-image-2)） |
| `um fal image` 普通图片 | `fal-ai/nano-banana-2`，默认 1K | 每张 $0.08；2K 按 1.5 倍、4K 按 2 倍、0.5K 按 0.75 倍（[模型页](https://fal.ai/models/fal-ai/nano-banana-2)） |
| `um fal rmbg` 抠图 | `fal-ai/birefnet/v2` | 页面显示每计算秒 $0（[模型页](https://fal.ai/models/fal-ai/birefnet/v2)） |
| `um fal sfx` 音效 | `fal-ai/elevenlabs/sound-effects/v2` | 每秒 $0.002（[模型页](https://fal.ai/models/fal-ai/elevenlabs/sound-effects/v2)） |
| `um fal model3d` 图片转 3D | `fal-ai/trellis-2`，默认分辨率 1024 | 每个模型 512p $0.25、1024p $0.30、1536p $0.35，默认调用为 $0.30（[模型页](https://fal.ai/models/fal-ai/trellis-2)）；批量生成前先运行 `um fal price fal-ai/trellis-2` 确认 |

示例算法（只算素材、不含重画和智能体费用）：

- 10 张默认精灵图：10 × $0.211 ≈ $2.11；
- 同样 10 张改成中等质量：10 × $0.053 ≈ $0.53；低质量约 $0.06；
- 10 张 1K 普通图片：10 × $0.08 = $0.80，需要抠图再加抠图费用；
- 一共 30 秒音效：30 × $0.002 = $0.06。

![fal 素材费示例：10 张精灵图高质量 $2.11、中等质量 $0.53、低质量 $0.06，10 张 1K 普通图片 $0.80，30 秒音效 $0.06，用条形长度对比](https://www.aifreeapi.com/posts/zh/universal-modder/img/fal-cost-example.webp)

实际花费取决于重画几次、用多大分辨率，以及有没有做 3D 和视频，这两类是最贵的。默认质量是高，像素风小图通常用不着：可以在需求里写明"精灵图用中等质量"，或者让智能体这样调用：

```bash
um fal sprite "a glowing blue sword, pixel art" --quality medium
um fal price openai/gpt-image-2
```

每次生成都会记进 `fal_manifest.jsonl`，回头可以对账。生成的透明 PNG 进游戏前要不要再检查边缘和透明通道，见 [GPT Image 2 透明背景 API：生成、保存与检查 PNG/WebP](/zh/posts/gpt-image-2-transparent-background)。

## 常见报错：现象、原因和解决办法

下面是项目 issue 里实际出现过的问题，截至 2026 年 10 月 8 日的状态。

### um kb search 报 UnicodeEncodeError: 'charmap'

在 Windows 上运行 `um kb search` 时崩溃，报 `UnicodeEncodeError: 'charmap' codec can't encode character`。原因是 Python 按控制台的旧编码输出，而知识库笔记里有这种编码表示不了的字符。issue #152 里报告的是英文系统的 cp1252 编码，中文 Windows 控制台默认是 GBK，会不会同样触发没有验证过。遇到同类编码报错时，先在 PowerShell 里设置 UTF-8 模式再运行：

```powershell
$env:PYTHONUTF8 = "1"
um kb search "terraria"
```

这个问题截至 10 月 8 日还没关闭，后续版本可能直接修掉。

### 安装时报 Error: spawn git ENOENT

用 Gemini CLI 安装时出现 `Failed to clone Git repository ... Error: spawn git ENOENT`，意思是找不到 Git，要么没装，要么不在 PATH 里。运行 `winget install --id Git.Git -e` 装好 Git，关掉终端重新打开，`git --version` 能出版本号再重试。另外 Windows 默认禁止执行 PowerShell 脚本，直接敲 `gemini` 可能被拦，维护者建议改用 `gemini.cmd`。

### claude plugin update 显示 already at the latest version (0.2.0)

10 月 6 日之前，插件清单里把版本号写死成了 0.2.0，Claude Code 靠版本号判断要不要更新，于是早期安装的用户一直停在缓存的旧版本上，`claude plugin update` 只会回复 `universal-modder is already at the latest version (0.2.0).`。10 月 6 日合并的 PR #108 去掉了这个固定版本号。如果你在那之前装过，卸载后重新安装一次，之后就能正常跟着更新。

### um scan --list 找不到装在 D:\Steam 的游戏

早期的 `um scan --list` 只在 `Program Files` 下找 Steam，Steam 装在 `C:\Steam`、`D:\Steam` 这类位置时，整个 Steam 库都会漏掉。10 月 6 日合并的 PR #95 改成从注册表读取 Steam 的实际位置。还遇到这个问题，说明你的副本是旧的，按上一条重新安装。

### tModLoader 打不开，智能体也不肯"修"

tModLoader 要求你的 Steam 库里有免费的 tModLoader 应用，没有就拒绝启动。这是所有权检查，Universal Modder 的规则是"去库里添加，不去改检查"。到 Steam 商店免费领取 tModLoader 就好。

## Universal Modder 会拒绝的游戏和请求

这些规则写在技能文件的 [Hard rules](https://github.com/rehan-remade/universal-modder/blob/main/skills/mod-any-game/SKILL.md) 和 [safety.md](https://github.com/rehan-remade/universal-modder/blob/main/skills/mod-any-game/references/safety.md) 里，你开口要求也不会变：

- **只改你拥有的游戏。** 它不下载游戏、ROM 或光盘镜像。
- **只在单机、离线模式或你自己架的服务器上改。** 受 EasyAntiCheat、BattlEye、Vanguard、官方服 VAC、Ricochet、ACE 保护的联网游戏客户端它不碰，safety.md 还列了 EA Javelin、nProtect、XIGNCODE 和 mhyprot。遇到这类游戏，它会建议改走离线模式、私服或官方工具（创意工坊、地图编辑器）。
- **不写多人游戏外挂。** 自瞄、透视、加速一律拒绝。
- **不绕过反作弊、DRM 或所有权检查。** 包括 Denuvo 和 Steam 自带的 DRM 壳（Steam Stub）。某个加载器只有破解 EXE 才能用时，它会停下。
- **不分发游戏文件。** 成品 mod 只包含你自己的代码、素材和补丁，解包出来的资源和反编译代码留在你本机。
- **动存档前先备份，动你的电脑前先问。** 接管鼠标键盘、往游戏目录装加载器、改注册表、删除文件、发布（包括向知识库提交 PR）都要你同意。

safety.md 自己也写明这些不是法律意见。有几件事值得在发布前知道：即使不带游戏素材，mod 也可能收到下架通知，Take-Two 在 2021 年让 GitHub 下架了逆向重写的 GTA III、罪恶都市代码并起诉作者，动视在 2024 年给 H2M mod 发过律师函；收费、商用会明显提高风险；fal 生成的素材按 fal 的条款可以使用，商用前还要看具体模型的许可；发布时如实说明用了 AI，部分 mod 社区明确禁止 AI 项目，社区里也有人公开反对这个工具。

另外，网上流传的"爆火 mod 下载"经常是恶意软件。加载器只从官方仓库和官方发布页下载；universal-modder.org 是基于这个开源项目的社区站，不是官方站，项目的源头是 [GitHub 仓库](https://github.com/rehan-remade/universal-modder)。

## 不装插件直接让智能体改游戏，差在哪

能力强的智能体不装插件也能改游戏。日本 YouTube 频道「さつきのOSS研究室」的测试称，Claude Code 在完全没调用这套技能的情况下，3 款游戏的 8 个改造任务全部完成，直接用命令行改的。这是单个作者的小样本，游戏和版本没有公开细节。

插件多出来的，是一套更稳的工作习惯和别人踩过的坑：

- **侦察和知识库。** `um scan` 一次报出引擎、版本、反作弊、加载器和存档位置；截至 10 月 8 日，知识库里有 78 篇游戏笔记、50 篇技术笔记，每篇记录了能用的确切版本、路线、验证方法和"现象→原因→解决"。一篇笔记存在不代表在你的游戏版本上一定能用，但能少走很多弯路。
- **安全网。** 备份存档、测试专用存档目录、按进程号结束游戏、联网反作弊游戏一律不碰，这些都写进了流程。
- **进游戏验证。** `um win` 负责启动、截图、只发给游戏窗口的输入和只录游戏声音的录屏，智能体能自己跑测试，而不是写完代码就说"应该可以了"。
- **素材管线。** `um fal` 出图出音效并记账，`um sprite` 抠图、缩放、调色板、拼精灵表，`um render3d` 把 3D 模型按游戏镜头渲染成多方向精灵。
- **发布检查。** `um publish check` 拦下不该分发的文件。

所以想让它按这套流程走，就在需求开头写上 `/universal-modder:mod-any-game`（Claude Code）或"用 mod-any-game 技能"（其他智能体），别指望它每次都自己想起来。

## 关于费用、Mac 和社区站的几个问题

### Universal Modder 要不要花钱？

工具本身免费开源，MIT 许可。要付钱的是你用的编程智能体（订阅或 API 用量）和 fal 素材生成（按张或按秒计费）；不用 fal 时可以接本机 ComfyUI，或者先用占位图。

### 用 Mac 能做 mod 吗？

能做侦察、查知识库、写代码和生成素材，但 `um win` 只在 Windows 原生或 WSL 下运行，智能体没法在 Mac 上自动启动游戏、截图和录屏，进游戏测试得你自己来。大多数能改的 PC 游戏本来也跑在 Windows 上。

### universal-modder.org 和 universalmodder.net 是官方网站吗？

都不是。universal-modder.org 自称基于这个开源项目的社区站，安装按钮复制的就是官方命令，上传 mod 需要免费注册；universalmodder.net 是另一个第三方教程站。官方源头只有 GitHub 仓库，README 里提到官方的 mod 分享站还在"即将推出"阶段。

### 做好的 mod 能发到哪里？

`publish-mod` 技能会帮你打包、写安装说明和致谢，可以发到 Nexus Mods、Steam 创意工坊、Thunderstore、mod.io 或 GitHub。发布前先跑 `um publish check`，并写明用了 AI。要不要把经验写成笔记提交回知识库，也是你说了算。