Universal Modder 安裝與使用教學

環境要求

一次裝好所有依賴

winget install Git.Git Python.Python.3.12 astral-sh.uv Gyan.FFmpeg
winget install BlenderFoundation.Blender   # 可選，用於 3D → 精靈圖

brew install git python ffmpeg uv
brew install --cask blender                 # 可選

sudo apt install git python3 python3-venv ffmpeg
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows、macOS 和 Linux：各自能用什麼

工具包大部分是跨平臺的。負責操控執行中游戲的部分（啟動、截圖、輸入、只錄遊戲聲音的視窗錄製）以 Windows 為主，因為遊戲基本都在 Windows 上。Agent 可以原生或透過 WSL2 操控 Windows 遊戲。

在 macOS 和 Linux 上，Agent 仍可用系統自帶的截圖錄影工具（screencapture、ffmpeg、xdotool）在遊戲裡測試，只是沒有預先配好。知識庫裡有在 Linux 上跑 xEdit、在 macOS 上用 Wine 跑 HL2 的筆記，說明這是可行的。

按 Agent 安裝：並排對照

每種方式安裝的都是同樣的技能（Agent Skills 格式）、fal MCP 服務和 um 命令列。

Claude Code

在 Claude Code 會話裡執行（不是在終端裡）：

/plugin marketplace add rehan-remade/universal-modder
/plugin install universal-modder@universal-modder

選擇 user 作用域，這樣在任何資料夾都能用；如果提示，再執行 /reload-plugins。完整步驟（包括 Claude Desktop 以及如何呼叫每個技能）見 Universal Modder + Claude Code 頁面。

OpenAI Codex

codex plugin marketplace add rehan-remade/universal-modder
codex plugin add universal-modder@universal-modder

Codex 從 .agents/skills 讀取技能，從 .codex/config.toml 讀取 MCP 配置。

Gemini CLI

gemini extensions install https://github.com/rehan-remade/universal-modder

擴充套件清單是 gemini-extension.json；指令來自 GEMINI.md，它指向 AGENTS.md。

VS Code + GitHub Copilot

1. 開啟設定，開啟 chat.plugins.enabled。
2. 開啟命令面板，執行 Chat: Install Plugin From Source。
3. 貼上 https://github.com/rehan-remade/universal-modder。

MCP 配置位於 .vscode/mcp.json。

Cursor

從 Cursor Marketplace 安裝，或複製儲存庫後開啟：Cursor 會自動讀取 AGENTS.md 和 .cursor/mcp.json。

OpenCode

git clone https://github.com/rehan-remade/universal-modder
cd universal-modder
opencode

opencode.json 會載入技能和 fal MCP 服務。

其他任何 Agent

# 只裝技能，放進 Agent 的技能目錄
npx skills add https://github.com/rehan-remade/universal-modder

# 或者整個儲存庫：在複製目錄裡啟動你的 Agent
git clone https://github.com/rehan-remade/universal-modder

單獨安裝 um 命令列

外掛安裝和複製儲存庫都會自動把 um 加到 PATH。如果你在別處使用技能，或想在普通終端裡用 um，把它當作工具安裝即可。它從 GitHub 安裝，不在 PyPI 上，所以 pip install universal-modder 是裝不上的。

uv tool install git+https://github.com/rehan-remade/universal-modder
# 或
pipx install git+https://github.com/rehan-remade/universal-modder

每個命令組都有帶示例的 --help。參見 um 命令參考。

設定 fal API 金鑰

在 fal.ai/dashboard/keys 獲取金鑰（需要先充值；金鑰只顯示一次，記得儲存）。fal MCP 服務和 um fal 都靠它工作。

export FAL_KEY="your-key"
# 永久生效
echo 'export FAL_KEY="your-key"' >> ~/.zshrc   # 或 ~/.bashrc

setx FAL_KEY "your-key"
# 然後開啟新終端並重啟 Agent

沒有金鑰？um comfy 可以用本地 ComfyUI 生成圖片。音訊、3D 和影片仍需要 fal。價格見費用頁。

檢查安裝

um --help
um kb search "terraria"       # 查已有實戰筆記（在儲存庫外也能用）
um scan --list                # 本機找到的遊戲
um fal price fal-ai/trellis-2 # 確認 FAL_KEY 可用

第一次使用：一個可回退的小改動

1. 選一個容易上手的遊戲有成熟載入器的遊戲最友好：Terraria（tModLoader）、星露谷物語（SMAPI）、Minecraft（Fabric/Forge）、用 BepInEx 的 Unity 遊戲、用 UE4SS 的虛幻遊戲。檢視遊戲庫。
2. 先讓它偵察
   提示詞複製

   我這份 Terraria 是什麼引擎？有人改過嗎（查一下知識庫）？你會走哪條路線？先不要改任何東西。

3. 讓它備份並搭建實驗環境Agent 會用 um backup create 給存檔做快照，使用單獨的配置或世界，並在安裝載入器前先問你。
4. 先做通一個切片
   提示詞複製

   加一把迴旋鏢：在敵人之間彈跳四次後返回。先用佔位精靈圖，在遊戲裡能用之後再用 fal 生成正式精靈圖。

5. 驗證，再擴充套件啟動遊戲親眼看一下，再提更多需求。長期專案記錄在 MODLOG.md 裡；新會話裡告訴它「讀 MODLOG.md 然後繼續」。

常見問題排查

新增 marketplace 時報 Git / SSH 錯誤

外掛市場是用 Git 複製的。如果你的電腦沒有 GitHub SSH 金鑰，讓 Git 對 GitHub 改用 HTTPS：

git config --global url."https://github.com/".insteadOf [email protected]:

安裝後看不到技能

執行 /reload-plugins（Claude Code）或重啟 Agent，並在 /plugin 裡確認外掛已啟用。

um: command not found

外掛安裝後開啟一個新終端，或按上面的方法用 uv tool install 安裝命令列，並確保 ~/.local/bin 在 PATH 裡（uv tool update-shell）。

um fal 提示缺少金鑰

FAL_KEY 必須設定在啟動 Agent 的那個環境裡。setx 或修改 shell 配置後要重啟 Agent。

um win 拒絕執行

它只能在 Windows 或 WSL2 上操控 Windows 遊戲。在 macOS/Linux 上請手動在遊戲裡測試。