MTGA 是一个基于本地代理的 IDE 固定模型服务商解决方案，适用于 Windows 和 macOS。

注意：本项目目前只支持 openai 格式的 api ，请确认。其他格式可以转为 openai 格式后再使用。

• MTGA
  • 简介
  • 目录
  • 更新日志
  • 快速开始
    • Windows 用户（GUI一键启动方式）
    • macOS 用户（应用程序安装）
      • 安装方式
      • 使用方法
  • macOS 解决 “包已损坏” 问题
    • 图形化解决方案
    • cli 解决方案
  • trae 端提示 “添加模型失败” 的排查方案
  • 从脚本启动
    • 第 0 步：环境准备
      • Windows
        • 第 1 步：生成自签名证书
        • 第 2 步：让 Windows 信任你的 CA 证书
        • 第 3 步：修改 Hosts 文件
        • 第 4 步：运行本地代理服务器 (Python)
        • 第 5 步：配置 Trae IDE
      • macOS
  • 😎 保持更新
  • 架构与依赖约束
  • 引用
  • Star History

最新日志详见： 最新发行版

历史日志归档： CHANGELOG.md

1. 从 GitHub Releases 下载最新版本的 MTGA_GUI-v{版本号}-x64.exe
2. 双击运行下载的 exe 文件（需要管理员权限）
3. 在打开的图形界面中，填写 API URL 和模型 ID
   • API URL 只需要填域名（端口号可选，不懂的就不要填），不需要填后面的路由，例如：https://your-api.example.com
   • 如果希望启用多模态能力，可以将模型名映射到内置多模态模型名上：
   • 
   • 
4. 点击"一键启动全部服务"按钮
5. 等待程序自动完成以下操作：
   • 生成并安装证书
   • 修改hosts文件
   • 启动代理服务器
6. 完成后，按照第 5 步：配置 Trae IDE进行IDE配置

1. 从 GitHub Releases 下载最新版本的 MTGA_GUI-v{版本号}-aarch64.dmg
2. 双击 DMG 文件，系统会自动挂载安装包
3. 将 MTGA_GUI.app 拖拽到 Applications 文件夹
4. 从启动台或 Applications 文件夹启动应用程序

1. 启动 MTGA_GUI.app（首次运行可能需要在系统偏好设置中允许运行）
2. 在图形界面中填写：
   • API URL：你的 API 服务地址（例如：https://your-api.example.com）
   • 如果希望启用多模态能力，可以将模型名映射到内置多模态模型名上：
   • 
   • 
3. 点击"一键启动全部服务"按钮
4. 程序会自动完成：
   • 生成并安装 SSL 证书到系统钥匙串
   • 修改 /etc/hosts 文件（需要管理员权限）
5. 需要手动在打开的钥匙串窗口中信任生成的证书，默认名称为 MTGA_CA
6. 启动本地代理服务器
7. 按照下方的 Trae IDE 配置 完成设置

如果启动 MTGA_GUI.app 时弹出这样的提示：

点击取消。然后参考以下步骤解决：

1. 到 Sentinel Releases 下载 Sentinel.dmg
2. 双击 Sentinel.dmg 文件，将 Sentinel.app 拖拽到 Applications 文件夹
3. 从启动台或 Applications 文件夹启动 Sentinel.app
4. 将本项目的 MTGA_GUI.app 拖拽到 Sentinel.app 的左侧窗口中
   • 

MTGA_GUI.app 将被自动处理并启动

1. 找到 MTGA_GUI.app 完整路径，如 /Applications/MTGA_GUI.app。
2. 打开终端（Terminal）应用程序。
3. 执行以下命令签名 MTGA_GUI.app：

   xattr -d com.apple.quarantine <应用完整路径>

   这会移除 MTGA_GUI.app 中的 com.apple.quarantine 扩展属性。
4. 启动 MTGA_GUI.app。

请检查：

• hosts 是否包含 127.0.0.1 api.openai.com 这一行，且未被注释掉（# 开头）。
• 确保没有其他程序正在使用端口 443（如浏览器、VPN 等）。
  • 可以使用以下命令检查：

    # windows
    netstat -ano | find ":443" | find "LISTENING"
    
    # macos
    netstat -lnp tcp | grep :443
    

  • 如果有进程在监听 443 端口，建议关闭该进程。

• 系统为 windows 10 以上
• 拥有管理员权限
• 安装 python 环境，推荐 python 3.10 以上
• 安装 git

打开 Git Bash:

# 切换到 ca 目录
cd "mtga/ca"

# 1. 生成 CA 证书 (ca.crt 和 ca.key)
./genca.sh

执行 ./genca.sh 时，它会问你 "Do you want to generate ca cert and key? [yes/no]"，输入 y 并按回车。之后会要求填写一些信息：

• Country Name (2 letter code) []: 填 CN (或其他国家代码)
• 其他字段（如 State, Locality, Organization, Common Name for CA）可以按需填写或留空，建议填X。Common Name 可以填 MTGA_CA 之类的。邮箱可以留空。

# 2. 生成 api.openai.com 的服务器证书 (api.openai.com.crt 和 api.openai.com.key)
# 这个脚本会使用同目录下的 api.openai.com.subj 和 api.openai.com.cnf 配置文件
./gencrt.sh api.openai.com

执行完毕后，在 mtga\ca 目录下你会找到以下重要文件：

• ca.crt (你的自定义 CA 证书)
• ca.key (你的自定义 CA 私钥 - 请勿泄露)
• api.openai.com.crt (用于本地代理服务器的 SSL 证书)
• api.openai.com.key (用于本地代理服务器的 SSL 私钥 - 请勿泄露)

1. 找到 mtga\ca\ca.crt 文件。
2. 双击 ca.crt 文件，打开证书查看器。
3. 点击"安装证书..."按钮。
4. 选择"当前用户"或"本地计算机"。推荐选择"本地计算机"（这需要管理员权限），这样对所有用户生效。
5. 在下一个对话框中，选择"将所有的证书都放入下列存储"，然后点击"浏览..."。
6. 选择"受信任的根证书颁发机构"，然后点击"确定"。
7. 点击"下一步"，然后"完成"。如果弹出安全警告，选择"是"。

⚠️警告：执行这一步之后，你将无法访问原来的 openai 的api。网页使用不影响。

你需要用管理员权限修改 Hosts 文件，将 api.openai.com 指向你的本地机器。

1. Hosts 文件路径: C:\Windows\System32\drivers\etc\hosts
2. 以管理员身份，使用记事本（或其他文本编辑器）打开此文件。
3. 在文件末尾添加一行：

   127.0.0.1 api.openai.com
   

4. 保存文件。

运行代理服务器之前：

1. 安装依赖:

   pip install Flask requests

2. 配置脚本:
   • 打开 trae_proxy.py 文件。
   • 修改 TARGET_API_BASE_URL: 将其替换为你实际要连接的那个站点的 OpenAI 格式 API 的基础 URL (例如: "https://your-api.example.com")。
   • 确认证书路径: 脚本默认会从 mtga\ca 读取 api.openai.com.crt 和 api.openai.com.key。如果你的证书不在此路径，请修改 CERT_FILE 和 KEY_FILE 的值，或者将这两个文件复制到脚本指定的 CERT_DIR。

运行代理服务器：

打开命令提示符 (cmd) 或 PowerShell 以管理员身份运行 (因为要监听 443 端口)，然后执行：

python trae_proxy.py

如果一切顺利，你应该会看到服务器启动的日志。

1. 打开并登录 Trae IDE。

2. 在 AI 对话框中，点击右下角的模型图标，选择末尾的"添加模型"。

3. 服务商：选择 OpenAI。

4. 模型：选择"自定义模型"。

5. 模型 ID：填写你在 Python 脚本中 CUSTOM_MODEL_ID 定义的值 (例如: my-custom-local-model)。

6. API 密钥：

   • 如果你的目标 API 需要 API 密钥，并且 Trae 会将其通过 Authorization: Bearer <key> 传递，那么这里填写的密钥会被 Python 代理转发。
   • Trae 配置 OpenAI 时，API 密钥与 remove_reasoning_content 配置相关。我们的 Python 代理不处理这个逻辑，它只是简单地转发 Authorization 头部。你可以尝试填写你的目标 API 所需的密钥，或者一个任意的 sk-xxxx 格式的密钥。

7. 点击"添加模型"。

8. 回到 AI 聊天框，右下角选择你刚刚添加的自定义模型。

现在，当你通过 Trae 与这个自定义模型交互时，请求应该会经过你的本地 Python 代理，并被转发到你配置的 TARGET_API_BASE_URL。

故障排除提示：

• 端口冲突：如果 443 端口已被占用 (例如被 IIS、Skype 或其他服务占用)，Python 脚本会启动失败。你需要停止占用该端口的服务，或者修改 Python 脚本和 Nginx (如果使用) 监听其他端口 (但这会更复杂，因为 Trae 硬编码访问 https://api.openai.com 的 443 端口)。
• 防火墙：确保 Windows 防火墙允许 Python 监听 443 端口的入站连接 (尽管是本地连接 127.0.0.1，通常不需要特别配置防火墙，但值得检查)。
• 证书问题：如果 Trae 报错 SSL/TLS 相关错误，请仔细检查 CA 证书是否已正确安装到"受信任的根证书颁发机构"，以及 Python 代理是否正确加载了 api.openai.com.crt 和 .key。
• 代理日志：Python 脚本会打印一些日志，可以帮助你诊断问题。

这个方案比直接使用 vproxy + nginx 的方式更集成一些，将 TLS 终止和代理逻辑都放在了一个 Python 脚本中，更适合快速在 Windows 上进行原型验证。

-> Mac OS 脚本启动方法

点击仓库右上角 Star 和 Watch 按钮，获取最新动态。

为避免模块耦合失控，项目遵循以下分层与依赖规则：

• UI -> actions -> services -> 领域模块（cert/hosts/network/proxy/update）-> runtime/platform
• UI 不得直接依赖领域模块，所有操作通过 actions/services 统一编排。
• 平台相关逻辑放在 modules/platform（或显式平台子模块）。

更多细节与错误处理规范见：docs/ARCHITECTURE.md。

ca目录引用自wkgcass/vproxy仓库，感谢大佬！