Skip to main content
Glama
Sign In
bg3coop

bg3coop

by IgnatAi401
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

bg3-coop-agent

中文 | English

和 AI agent 一起玩《博德之门3》：你在前台操控自己的主角，agent 在后台操控一名队友。支持两人解除链接，各自探索、各自对话，战斗时轮流行动。

agent 不会动你的鼠标和键盘，不占用你的前台和屏幕视野。它通过 Script Extender 的调试端口，在游戏里用脚本控制自己的角色，并且只能看到它这个角色看得见的东西。

组成

  • 注入到游戏里的 Lua 脚本：负责感知和行动，不需要装 mod。

  • 一个可选 mod：将 agent 需要的游玩记录数据一起保存进存档，防止读档时记忆错乱或丢失。

  • MCP 服务器：把游戏操作包装成 agent 可以调用的工具，游玩守则也写在里面。支持 Claude Code、Codex 和 DeepSeek Harness。

  • bg3coop 命令：setup 配置游戏，doctor 检查一切是否就绪。

测试过的版本：游戏 4.1.1.7631656（DirectX 11），Script Extender v33。

Related MCP server: LÖVE2D MCP Server

安装

游戏和 agent 装在同一台 Windows 电脑上。下面的命令用 uv（最省事）；没有 uv 或想用自己的 Python 环境（3.10 以上），见安装说明。

最省事的办法：对你的 agent 说「按 https://github.com/IgnatAi401/bg3-coop-agent/blob/main/docs/install-for-agents.md 帮我装好 BG3 Co-op」，它会一步步带你安装。想自己装的话：

  1. 下载 Script Extender（Norbyte/bg3se），把 DWrite.dll 放进游戏的 bin 目录，例如 D:\SteamLibrary\steamapps\common\Baldurs Gate 3\bin。

  2. 关掉游戏，在 PowerShell 里运行：

    uvx --from https://github.com/IgnatAi401/bg3-coop-agent/releases/download/v0.1.1/bg3coop-0.1.1-py3-none-any.whl bg3coop setup

    setup 会从 Steam 找到游戏，在 bin 目录写好 ScriptExtenderSettings.json（打开 Lua 调试端口 9998，原有设置保留），并检查 DWrite.dll。找不到游戏时用 --game-dir 指定安装目录。

    它还会装一个小 mod「BG3 Co-op Memory」：放进 %LOCALAPPDATA%\Larian Studios\Baldur's Gate 3\Mods，并在 modsettings.lsx 里启用（原文件备份为 modsettings.lsx.bg3coop-backup）。这个 mod 只记录队伍走过的地方和 agent 的剧情笔记，存在存档里。游戏退出时会改写 mod 列表，所以要在游戏关着时运行 setup。

    这个 mod 是可选的，不想装就在命令末尾加上 --no-mod。这样 setup 不会碰 Mods 文件夹和 modsettings.lsx，开着游戏也能运行。不装 mod 时其他功能照常，但是记忆不再跟随存档，存档读档时可能导致 agent 记忆错乱，doctor 也会给一条提醒（WARN），可以忽略。装了 mod 以后存的档会把它列为所需 mod，之后再卸掉 mod，读这些档时游戏会提示缺少 mod。

  3. 把它接到你的 agent 上（三选一）：

    • Claude Code：在 Claude Code 里输入

      /plugin marketplace add IgnatAi401/bg3-coop-agent
/plugin install bg3coop@bg3-coop-agent

    • Codex：在终端运行

      codex plugin marketplace add IgnatAi401/bg3-coop-agent
codex plugin add bg3coop@bg3-coop-agent

    • DeepSeek Harness：在 dsh 的「插件」页点「添加插件」，填入下面的地址后安装并启用；或者在终端运行 dsh plugin add 加上这个地址（不是默认 profile 时加 --profile <名字>）。

      https://github.com/IgnatAi401/bg3-coop-agent/releases/download/v0.1.1/dsh-bg3coop-0.1.1.tgz

    三个插件都用 uv 启动 MCP 服务器；没有 uv 时让 agent 按安装说明换别的方式。

git clone https://github.com/IgnatAi401/bg3-coop-agent
cd bg3-coop-agent
uv sync
uv run bg3coop setup
cd play
claude

play/ 里的 .mcp.json 让 Claude Code 直接用这份源码启动 MCP 服务器。

更新

有新版时，doctor 和 agent 都会提醒你。插件和程序一起发版，更新插件就会换成新版程序：

  • Claude Code：在 Claude Code 里输入 /plugin marketplace update bg3-coop-agent。也可以在 /plugin 的 Marketplaces 里选中它，打开 Enable auto-update，以后自动更新。

  • Codex：在终端运行 codex plugin marketplace upgrade bg3-coop-agent。

  • DeepSeek Harness：用新版本的地址再装一次（把上面地址里的两处版本号换成新的），会直接覆盖旧版。

然后重启 agent（或开个新会话），关掉游戏再运行一次 setup（命令里的版本号也换成新的），让 Memory mod 也更新。没装 mod 的话，照样加上 --no-mod，开着游戏运行也行。不是用插件装的，按安装说明末尾更新。

开始一局

  1. 启动游戏（Script Extender 首次启动时会自动下载），读取存档，确保想交给 agent 的队友在队伍里。启动时可能弹出「游戏文件损坏」之类的提示，这是装了 Script Extender 和 mod 后的常见现象，一般可以无视，直接继续。

  2. 运行检查（可选）：

    uvx --from https://github.com/IgnatAi401/bg3-coop-agent/releases/download/v0.1.1/bg3coop-0.1.1-py3-none-any.whl bg3coop doctor

    每一行都是 OK 就可以开始。FAIL 那一行会写明要怎么改。游戏一次只接受一个连接，agent 正连着游戏时 doctor 会提示这一点，并跳过剩下的检查。

  3. 开一个新的 agent 会话，对它说「开始玩，你控制影心」。agent 会先接管并解除这名队友的链接，然后开始自己探索。

一起玩时要知道的

IMPORTANT

模型能力很关键。 下面这些功能能否正常发挥，都取决于 agent 能否读懂规则、调对工具。BG3 规则繁多，自由度极高，每次判断都要综合大量信息，模型越强，配合越顺畅，建议使用能力更强的模型。

确认 agent 读过游玩守则。 守则随 MCP 服务器下发，但有的客户端不会把它交给模型，这时 agent 要自己调用 rules 工具才能看到。如果 agent 不按规矩来（比如替你点对话、在你的回合里行动、不在面板里回话），对它说一句「先调用 rules 看看游玩守则」。

  • agent 做不到的事：其他事 agent 基本都能自己做（探索、对话和检定、战斗和施法、使用物品、换装备、交易、回营地和传送等），下面这些目前无法做到：

    • 开锁、解除陷阱

    • 扒窃 NPC

    • 开局创建角色

    • 升级加点

    • 炼金和物品合成

    • 用夺心魔蝌蚪解锁能力

    • 短休和长休

    • 进入回合制模式

    • 存档、读档

  • 对话：BG3 一次只有一个对话界面，显示在你的屏幕上。agent 的角色发起的对话由 agent 选择回答，你也可以直接替它点。你的对话 agent 不会碰。

  • 战斗：回合制下轮到 agent 的角色时，镜头会切过去，等它行动完并结束回合即可。轮到你时它会等待。agent 施法会正常消耗动作、附赠动作和法术位。如果你和 agent 的先攻相邻（共享回合），它结束后游戏仍显示共享回合，你结束自己的部分即可。

  • 营地和传送点：agent 可以自己回营地、离开营地，或传送到解锁过的、当前地图上的传送点。解除链接时只有它的角色会传送，你和你的队伍留在原地。战斗中或对话中不能用。

  • 反应：接管后，agent 角色不耗法术位的反应（如守御闪光、借机攻击）会自动使用，耗法术位的默认不用，你的屏幕上不会再弹它的反应询问框。可以让 agent 用 reactions 调整，regroup 时恢复原设置。

  • 聊天面板：agent 开始工作后，游戏里会出现一个「BG3 合作」小窗，按 F10 显示或隐藏；agent 发来消息时面板会自动打开。重启游戏或读档后，面板要等 agent 下一次行动才会回来；如果一直没出现，对 agent 说一句「面板不见了」。

    • 标题栏显示 agent 接管的角色。agent 发来新消息时标题栏会闪几下，然后一直显示「N 条新消息」，直到你把鼠标移到面板上、点输入框或发消息。

    • 标题下面一行实时显示 agent 在做什么：「施法 火焰箭 → 地精 · 3 秒」表示动作正在进行；「思考中 · 20 秒 · 上一步：…」表示它在想下一步；两分钟没有动作会提示它可能停下了。战斗中轮到 agent 时，还会显示它有没有收到回合（「轮到影心了 · 还没收到（8 秒）」或「影心的回合 · 已收到」）。

    • 「聊天」页是对话；「动作记录」页列出 agent 最近做过的事，最新的在最下面，失败的标红。

    • 四个快捷按钮：跟上我、停下、等我、自由行动。

    • 在输入框里打字、回车发送，agent 下次调用工具时就会看到；它的回复也显示在这里。在输入框里打字不会触发游戏按键。

    • agent 拿不准时会提问，问题下面有 Yes / No 按钮，也可以直接打字回答；一段时间不回答，它会自己继续。

    • 面板关着时，agent 的留言会强制面板打开。

  • 指给 agent 看：用鼠标中键单击一个角色、物品或地面，agent 就知道你指的是什么（按住中键拖动仍是转视角，不算）。接着在面板里说「打这个」「去那里」「把这个捡起来」即可。

  • 只有 agent 在持续行动时才会读到消息：它每次调用工具都会顺带看一眼面板。如果它在 agent 那边停下来等你回话，游戏里的消息就收不到。可以设置让它一直循环：Claude Code 可以用 /loop，dsh 可以用 goal 或 ralph 模式；或强调没事干时调用 wait 而不是停下来。

  • 弹窗：遇到紧急情况，agent 会额外弹一个消息框，每分钟最多一次。

  • 你的主角：默认是你自己创建的主角。你点选、切换到其他角色（包括 agent 的角色）不会改变这一点；如果想指定别人，开局时告诉 agent。

  • 探索记忆：agent 会优先去队伍还没去过的方向。走过的地方由 BG3 Co-op Memory mod 记在存档里，没连 agent 时也照记，读哪个档就是那个档当时的记录，不同存档互不影响。装 mod 之前走过的地方不算。这个 mod 是可选的（setup --no-mod 不装）：没装时，agent 只记得这次读档以后走过的地方，目标和剧情笔记也会在读档时清空。装了这个 mod 后存的档会把它列为所需 mod。

  • agent 的笔记：agent 会把长期目标、答应过的事、重要地点记成笔记，这些存在存档里，读旧档就回到那时的样子。它给自己定的角色设定和你的偏好存在本机 %LOCALAPPDATA%\bg3coop\notes，每个周目一个文件，读档不会忘。更新 bg3coop 后如果 doctor 提示 mod 版本旧了，关掉游戏再运行一次 setup（见上面的「更新」）。

  • 查 wiki：agent 可以用 wiki 查 bg3.wiki（英文），了解法术、物品、敌人的机制和抗性。任务解法、谜题答案和剧情走向不会主动查，避免剧透。电脑网络环境要能够访问这个网站，访问不了时 agent 照常游玩。

  • 读档后游戏里的 Lua 状态会清空，MCP 服务器会自动重新注入脚本，并重新接管同一名队友。

工具一览

工具

作用

rules

游玩守则（dsh 不会自动把它交给 agent，agent 自己读）

party / set_agent / regroup

查看队伍、接管队友、重新链接

status / look / spells

角色状态、视野内（约 22 米）的人和物和还没去过的方向、今天能用的行动和法术

prepare

更换准备的法术（战斗外，不超过游戏给的上限）

reactions

查看和设置反应：自动使用、不用、询问人类

move / use / talk

走动、使用物体（门、箱子、拉杆）、对话

sneak / sight

潜行和停止潜行；查看附近的人朝哪看、视野锥多大、谁看得见自己，以及没人看着的位置。潜行时 move 会避开别人的视野锥

container / take

查看并拿取身边容器里的物品

inventory / use_item / equip / give

查看背包和装备、喝药水或读卷轴、换装备、把物品交给你（或其他队友）

throw

扔东西：背包里的投掷物、武器，地上的物品，甚至角色

trade

和商人买卖（用游戏自己的交易窗口和价格）。每次先在聊天面板问你同意，再问你要一起交易（窗口在你屏幕上打开）还是让它自己在后台交易（窗口藏起来，你的屏幕照常）

travel

回营地或离开营地、用已解锁的传送点快速旅行（只有 agent 自己过去）

combat / examine

先攻顺序、各人 HP 和状态、上回合以来发生了什么；查看敌人的 AC、抗性和特性

cast / end_turn

攻击或施法（可升环）、结束回合

dialogue / choose / roll

读取并回答自己角色的对话，替自己的检定掷骰（你能看到骰子）

wait / job_status / stop

等待游戏事件、继续等长动作、停下

quests

读游戏任务日志里进行中的任务

wiki

查 bg3.wiki（英文）：法术、物品、敌人的机制。需要游戏电脑能访问这个网站，网络不通时 agent 照常玩，只是查不了

notes

agent 自己的笔记：目标、经历、地点（存进存档），角色设定和你的偏好（存在本机）

say / ask

在聊天面板里给你留言，紧急时加弹窗；向你提是非题并等回答

许可证

MIT，见 LICENSE。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

  • LÖVE2D MCP Server

    InfiniteLoopRD
    A
    license
    A
    quality
    B
    maintenance
    Enables AI assistants to interact with running games in real time — introspecting game state, simulating keyboard and mouse input to actually play, capturing screenshots, executing Lua code, hot-reloading files, and receiving push notifications when state changes.
    8
    MIT

  • botm

    huerji
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to develop Banner of the Maid mods by reading and modifying game data (characters, items, weapons, skills, dialogue, saves, portraits) and to perform live in-game verification via launching the game, taking screenshots, and clicking by coordinates.
    2
    MIT

  • DD1-Copilot

    FengJPC
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables agent-controlled Darkest Dungeon gameplay by providing game state, tactical context, validated semantic actions, and persistent campaign memory to AI assistants.
    MIT