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

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 的写法为准。

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

智能体怎么选。 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：现在该选哪个编程智能体？；完全没接触过 Claude Code 的话，先看 Claude Code 是什么：能做什么、在哪用、怎么收费。

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

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

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

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

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

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 的安装教程）：

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 密钥，fal MCP 服务和 um fal 都靠它：

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

# 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 三种方法与国内使用），再按下面的顺序走：

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 插件文档说明，启用的插件即使这一轮没用到，技能名称和描述也会每轮占用上下文和用量；不改游戏的时候，用 /plugin 或在终端运行 claude plugin disable 把它停用。第二，插件以你的用户权限运行代码，而浏览器里的 claude.ai/code 云端会话不加载本机插件，改本机游戏只能在本地终端、桌面应用的本地会话或 VS Code 扩展里做。

Codex、Gemini CLI 和本地模型

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

Gemini CLI。 README 仍然列着它，但 Google 的停用说明写明：从 2026 年 6 月 18 日起，Gemini Code Assist 个人版、Google AI Pro、Google AI Ultra 账号不能再用"使用 Google 登录"访问 Gemini CLI，Standard 和 Enterprise 订阅不受影响。只有你现有的认证方式还能用时，这条路才走得通，详情见 Gemini CLI 还能用吗？个人账号停服范围与迁移指南。

本地模型。 维护者在 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 接入文档（文档标注适用于 Codex CLI 0.160.0，更新日期 2026 年 10 月 5 日）给的配置是：先把密钥写进环境变量 LAOZHANG_API_KEY，再在 ~/.codex/config.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。

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

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

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

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

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

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

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

/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 启动游戏前，智能体应该先运行：

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

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

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

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

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

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

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

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

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

um fal 各配方的默认模型写在 um/fal.py 里，截至 2026 年 10 月 8 日 fal 模型页上的标价如下（fal 的价格，不是 OpenAI 或 Google 的直连价）：

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

• 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。

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

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。

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

下面是项目 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 模式再运行：

$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 和 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 仓库。

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

能力强的智能体不装插件也能改游戏。日本 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。要不要把经验写成笔记提交回知识库，也是你说了算。