安装

下载安装包，一键装上 ModelBridge

提供 Windows / macOS / Linux 三平台预编译包，免 Python 依赖，下完双击或解压即用。

1
推荐

GitHub Release · 预编译安装包

下载对应平台的安装包，无需 Python，下完即用。 Windows 提供 .exe 安装器，macOS / Linux 提供 .tar.gz。

🪟 Windows x64 · .exe 🍎 macOS Apple Silicon · .tar.gz 🐧 Linux x64 · .tar.gz
前往 GitHub Releases 下载 最新版直链
文件名参考 (v1.2.1)
  • 🪟 ModelBridge-Setup-1.2.1.exe — Windows 安装器（Inno Setup，自动加 PATH）
  • 🍎 mbridge-1.2.1-macos-arm64.tar.gz — Apple Silicon
  • 🐧 mbridge-1.2.1-linux-x86_64.tar.gz — glibc x64
Windows 安装器说明

双击 .exe → 默认装到 %LOCALAPPDATA%\Programs\ModelBridge\（不需管理员）→ 自动加 PATH → 新开一个 CMD 窗口 跑：

mbridge version
mbridge init
mbridge model init

未签名，Windows SmartScreen 会提示"未知发布者"，点 More info → Run anyway 即可。

macOS / Linux 解压 
# macOS
tar xzf mbridge-1.2.1-macos-arm64.tar.gz -C ~/.local
echo 'export PATH="$HOME/.local/mbridge:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Linux
tar xzf mbridge-1.2.1-linux-x86_64.tar.gz -C ~/.local
ln -sf ~/.local/mbridge/mbridge ~/.local/bin/mbridge

mbridge version

macOS 首次运行若被 Gatekeeper 拦截：xattr -d com.apple.quarantine ~/.local/mbridge/mbridge。 macOS Intel / Linux arm64 暂未提供预编译包，可改用 npm install -g @crisxie/mbridge（同样需要对应平台二进制），或从源码安装（见下方）。

2

npm · 投递壳

npm 包内是薄薄一层 JS，装好后自动从 GitHub Release 下载对应的预编译二进制（自带 Python 运行时，无需本地 Python）。

Windows x64 macOS Apple Silicon Linux x64 (glibc) macOS Intel / Linux arm64 · 暂未提供预编译包 
npm install -g @crisxie/mbridge@latest

mbridge   # 直接进入会话
环境变量 / 镜像 / 升级 
# 跳过下载（CI/开发用）
MBRIDGE_SKIP_DOWNLOAD=1 npm install -g @crisxie/mbridge@latest

# 自定义下载地址（镜像）
MBRIDGE_DOWNLOAD_BASE=<url> npm install -g @crisxie/mbridge@latest

# 升级 / 卸载
npm install -g @crisxie/mbridge@latest
npm uninstall -g @crisxie/mbridge

包名 @crisxie/mbridge。 如果 npm 全局装到需要 sudo 的目录，前面加 sudo，或用 nvm / n 之类避免。

从源码启动 · 不推荐普通用户使用 仅在你打算改 ModelBridge 源码或参与贡献时用 · 需要 Python 3.10+ 
git clone https://github.com/CrisXie4/ModelBridge.git
cd ModelBridge
pip install -e ".[dev]"

pytest              # 跑测试
ruff check .       # lint (CI 硬门禁)

注册了 mbridge 与 modelbridge 两个入口，等价。 Windows 注意：先关掉所有正在跑的 mbridge 再 pip install -e .，否则可能因 mbridge.exe 被占用报 WinError 32。

下一步

装好后 30 秒跑起来

不管用哪种方式装的，下面三步都一样。

1

初始化

创建 ~/.modelbridge/ 目录，写默认配置。

mbridge init
2

添加模型

交互式 model init 会引导你选 provider、填 key。 key 进 keyring，跨 shell 也能用。

mbridge model init
# 选 DeepSeek → 输入 deepseek-chat
# API key 直接粘，回车后存进系统 keyring
3

进会话

在任意项目目录里跑 mbridge，AI 就能读 / 写 / 编辑文件。

cd ~/my-project
mbridge -m deepseek-chat
# 或：mbridge -m qwen-coder --allow-bash
可选

还要装浏览器侧边栏？

纯命令行已经够用。 想让 AI 在侧边栏里读 / 操作你当前浏览的网页，再装扩展。

  1. 从 Releases 下载 modelbridge-extension.zip 并解压。
  2. 注册 Native Messaging 宿主：mbridge bridge install
  3. 打开 chrome://extensions → 开启开发者模式 → 加载已解压的扩展程序 → 选解压出的文件夹。
  4. 回到 chrome://extensions 重新加载扩展，点工具栏图标即可在侧边栏里聊天。

API key 必须放在 keyring / config.yaml 里 —— 浏览器从 GUI 启动宿主，读不到 export 的环境变量。

查看扩展完整文档 →