Quản lý mô hình và nhà cung cấp tác nhân AI bằng Magpie

Magpie làm gì

Magpie cung cấp một nơi duy nhất để xem và thay đổi các mô hình được các tác nhân AI cài đặt trên máy tính của bạn sử dụng. Ứng dụng có sẵn dưới dạng ứng dụng thanh menu, cửa sổ máy tính để bàn thông thường, giao diện người dùng trong terminal và công cụ dòng lệnh.

Thay vì chỉnh sửa thủ công nhiều tệp JSON, TOML, YAML và tệp môi trường, bạn có thể chọn một tác nhân, chọn một trường và gán một mô hình. Magpie chỉ sửa đổi cài đặt liên quan, đồng thời giữ nguyên chú thích, thứ tự và thụt lề khi có thể. Các thao tác ghi của Magpie là nguyên tử.

Hiện Magpie nhận diện Claude Code, Codex, Gemini CLI, OpenCode, Pi, Goose, Cursor CLI, Copilot CLI và Crush. Chỉ các tác nhân đã được cài đặt hoặc cấu hình mới xuất hiện trong giao diện.

Tính năng chính

• Nhiều giao diện: Sử dụng ứng dụng máy tính để bàn, bảng điều khiển thanh menu, giao diện terminal hoặc CLI thuần túy.
• Chỉnh sửa cấu hình chính xác: Magpie thay đổi khóa đã chọn mà không viết lại phần còn lại trong cấu hình của tác nhân.
• Cổng cục bộ thống nhất: Các tác nhân có thể truy cập mô hình từ nhiều nhà cung cấp thông qua một điểm cuối loopback duy nhất.
• Chuyển đổi API: Cổng hỗ trợ các yêu cầu tương thích với OpenAI Chat Completions, OpenAI Responses, Anthropic Messages và Google Gemini, bao gồm truyền dữ liệu trực tiếp và lệnh gọi công cụ.
• Dùng chung gói đăng ký: Tài khoản Claude Code, Codex và Copilot hiện có có thể xuất hiện dưới dạng nhà cung cấp cho các tác nhân khác.
• Danh mục mô hình trực tiếp: Magpie lấy danh sách mô hình từ các nhà cung cấp và bổ sung dữ liệu từ models.dev.
• Cấu hình sẵn cho nhà cung cấp: Có sẵn cấu hình cho các nhà cung cấp và dịch vụ như Anthropic, OpenAI, Gemini, DeepSeek, Kimi, GLM, MiniMax, Qwen, Mistral, Groq, xAI, OpenRouter, Together, Ollama và LM Studio.
• Hồ sơ: Lưu tất cả cài đặt tác nhân hiện tại dưới một tên và khôi phục cùng lúc sau đó.
• Bản dựng gốc nhỏ gọn: Bản dựng máy tính để bàn sử dụng webview của hệ điều hành thay vì đóng gói một runtime trình duyệt.

Cài đặt Magpie

Cài đặt bản phát hành dựng sẵn

Tải ứng dụng máy tính để bàn cho macOS, Windows hoặc Linux từ usemagpie.ai. Bạn cũng có thể chạy tập lệnh cài đặt:

curl -fsSL https://usemagpie.ai/install.sh | sh

Trên Linux, trình cài đặt chọn ứng dụng máy tính để bàn khi WebKitGTK 4.1 khả dụng; nếu không, trình cài đặt sẽ cài bản dựng dòng lệnh. Các bản phát hành macOS được ký và công chứng. Bản dựng Windows và Linux hiện chưa được ký, vì vậy Windows SmartScreen có thể hiển thị cảnh báo trong lần khởi chạy đầu tiên.

Magpie kiểm tra bản cập nhật ở chế độ nền. Ứng dụng máy tính để bàn sẽ cài đặt bản cập nhật khi khởi động lại hoặc thoát, còn người dùng terminal có thể cập nhật rõ ràng:

magpie update

Cài đặt từ mã nguồn Go

Nếu đã cài đặt Go, hãy cài đặt trực tiếp phiên bản mới nhất:

go install github.com/yetone/magpie@latest

Dựng kho mã cục bộ

Kho mã cung cấp một số mục tiêu Make:

make build            # Tệp nhị phân ứng dụng máy tính để bàn
make app              # Ứng dụng thanh menu macOS
make cli              # Bản dựng chỉ dành cho terminal, không có cgo
make release          # Bản dựng ứng dụng gốc và CLI đa nền tảng
make release-windows  # Bản dựng ứng dụng Windows amd64 và arm64
make release-linux    # Ứng dụng Linux cho kiến trúc hiện tại

Để dựng ứng dụng máy tính để bàn Linux, cần có libgtk-3-dev và libwebkit2gtk-4.1-dev. Bản dựng Go thuần túy phải sử dụng build tag gtk3. Windows sử dụng runtime WebView2 đi kèm hệ điều hành.

Mở giao diện

Chọn giao diện phù hợp với quy trình làm việc của bạn:

magpie          # Mở cửa sổ và biểu tượng thanh menu
magpie tray     # Chỉ chạy biểu tượng thanh menu
magpie tui      # Mở giao diện terminal
magpie ls       # Liệt kê các tác nhân được phát hiện và cài đặt hiện tại

Giao diện máy tính để bàn cho phép bạn nhấp vào bất kỳ giá trị hiện tại nào để mở bộ chọn đã lọc. Nhập để tìm kiếm hoặc nhập giá trị tùy chỉnh, rồi nhấn esc để đóng bộ chọn.

Trong giao diện terminal, dùng các phím mũi tên để chọn tác nhân và trường, nhấn Enter để mở bộ chọn tương ứng, rồi nhập để lọc các lựa chọn có sẵn. Nhấn q để thoát.

Thêm nhà cung cấp mô hình

Xem các cấu hình sẵn có

Bắt đầu bằng cách liệt kê các nhà cung cấp mà Magpie đã biết:

magpie presets

Các cấu hình sẵn được nhóm thành nhà cung cấp, dịch vụ chuyển tiếp và dịch vụ cục bộ. Cấu hình sẵn được lưu trữ thường chỉ cần khóa API:

magpie provider add deepseek sk-…

Các nhà cung cấp cục bộ như Ollama không yêu cầu khóa:

magpie provider add ollama

Magpie không đọc khóa nhà cung cấp từ môi trường shell của bạn. Thay vào đó, hãy thêm khóa thông qua ứng dụng hoặc các lệnh nhà cung cấp.

Thêm nhà cung cấp tương thích với OpenAI tùy chỉnh

Có thể cấu hình nhà cung cấp tùy chỉnh bằng tên, URL cơ sở, khóa và danh sách mô hình cụ thể:

magpie provider add "My Relay" url=https://relay.example.com/v1 key=sk-… models=gpt-5.5,claude-sonnet-5

Nhà cung cấp tùy chỉnh có thể dùng url= cho cơ sở tương thích với OpenAI, anthropic= cho cơ sở tương thích với Anthropic hoặc dùng cả hai. Sử dụng responses= khi nhà cung cấp có điểm cuối Responses riêng. Đối số tùy chọn catalog= có thể mượn siêu dữ liệu từ một nhà cung cấp trên models.dev.

Xem và kiểm tra nhà cung cấp

Sử dụng các lệnh sau để xem xét nhà cung cấp, làm mới danh sách mô hình, kiểm tra API, thay khóa hoặc xóa một mục:

magpie providers
magpie provider deepseek
magpie provider models deepseek
magpie provider test deepseek
magpie provider key deepseek sk-…
magpie provider rm deepseek
magpie models

magpie provider test thực hiện một yêu cầu nhỏ cho mỗi API được hỗ trợ và báo cáo độ trễ. Trong ứng dụng máy tính, thẻ Providers cung cấp các tùy chọn tương đương để thay đổi khóa, chọn các model được cung cấp, kiểm tra provider và gán model của chúng cho các agent.

Chuyển Đổi Model Của Agent

Các model được gateway cung cấp sử dụng định dạng provider/model. Bạn cũng có thể chọn các model gốc của agent bằng tên thông thường của chúng.

Ví Dụ CLI Cơ Bản

magpie claude opus
magpie codex gpt-5.6-sol
magpie codex effort high
magpie codex xhigh
magpie codex deepseek/deepseek-chat
magpie claude moonshot/kimi-k2.5
magpie gemini auth api-key
magpie opencode anthropic/claude-sonnet-5
magpie oc small anthropic/claude-haiku-4-5

Tên agent chấp nhận các tiền tố như cc, oc và gem. Các agent theo provider như OpenCode, Pi, Goose và Crush sử dụng mã định danh provider/model.

Cấu Hình Các Tầng Claude Code

Claude Code có thể gán các model riêng cho những tầng như opus, sonnet, haiku và fable. Ví dụ, chỉ gán một model DeepSeek cho tầng haiku:

magpie claude haiku deepseek/deepseek-v4-flash

Xóa lựa chọn dành riêng cho tầng đó để đưa nó về model chính của Claude Code:

magpie claude haiku ""

Khi chọn một model gateway, Magpie quản lý URL cơ sở Anthropic, token và các biến model trong settings.json của Claude Code. Khi chọn model gốc, Magpie sẽ xóa các thiết lập gateway và khôi phục các giá trị trước đó.

Khởi Động Lại Agent Sau Khi Chuyển Đổi

Agent đọc cấu hình khi khởi động. Một phiên đang chạy sẽ tiếp tục sử dụng model trước đó cho đến khi bạn bắt đầu một phiên mới.

Điều này đặc biệt quan trọng với Codex, vì Codex đọc danh mục model khi khởi động và phải được khởi động lại sau khi chuyển đổi.

Lưu Và Khôi Phục Hồ Sơ

Một hồ sơ lưu lại các thiết lập hiện tại của mọi agent được phát hiện. Tính năng này hữu ích khi bạn cần duy trì các cấu hình riêng cho công việc, thử nghiệm, suy luận cục bộ hoặc các tác vụ nhạy cảm về chi phí.

magpie save work
magpie use work
magpie profiles
magpie rm work

Trong ứng dụng máy tính, các hồ sơ xuất hiện dưới dạng chip ở cuối chế độ xem chính. Nhấp vào một chip để áp dụng, dùng nút xóa của chip để xóa hoặc chọn + save current để tạo hồ sơ.

Trong giao diện terminal, nhấn s để lưu thiết lập hiện tại và p để áp dụng hoặc xóa hồ sơ.

Sử Dụng Agent Đã Đăng Nhập Làm Provider

Magpie có thể cung cấp các gói đăng ký Claude Code, Codex và Copilot hiện có dưới dạng provider. Sau khi đăng nhập thông qua agent gốc, các model khả dụng của agent sẽ xuất hiện trong magpie providers và trong bộ chọn model của các agent khác.

• Model Claude Code sử dụng các mã định danh như claude/claude-sonnet-5.
• Model thuộc gói đăng ký Codex sử dụng các mã định danh như codex/gpt-5.5.
• Model Copilot sử dụng các mã định danh như copilot/claude-sonnet-4.5.

Magpie đọc thông tin xác thực hiện có của agent khi cần và không sao chép chúng vào kho provider riêng. Nếu agent gốc luân phiên token, Magpie sẽ tuân theo quy trình làm mới của agent đó và ghi token mới vào vị trí agent mong đợi. Việc đăng xuất sẽ xóa provider tương ứng.

Gói đăng ký Claude yêu cầu binary claude cục bộ chính thức được cài đặt và đăng nhập. Magpie chạy binary đó và kết nối các công cụ của bên gọi vào lượt tương tác đang hoạt động qua MCP. Hỗ trợ đăng nhập Google của Gemini CLI đang được lên kế hoạch nhưng hiện chưa khả dụng dưới dạng provider dùng chung.

Kết Nối Ứng Dụng Khác Với Gateway

Gateway của Magpie mặc định lắng nghe tại 127.0.0.1:3425 và khởi động cùng ứng dụng. Để chỉ chạy gateway, hãy dùng:

magpie serve

Đặt MAGPIE_ADDR để thay đổi địa chỉ lắng nghe. Việc liên kết với loopback mặc định giữ gateway ở cục bộ trên máy tính của bạn.

Các Endpoint API Được Hỗ Trợ

• /v1/chat/completions cho OpenAI Chat Completions.
• /v1/responses cho OpenAI Responses.
• /v1/messages cho Anthropic Messages.
• /v1/messages/count_tokens cho việc đếm token Anthropic.
• /v1beta/models/{model}:generateContent cho việc tạo nội dung Gemini, cùng các biến thể truyền trực tiếp và đếm token.
• /v1/models và /v1beta/models cho danh mục model.

Khóa API có thể là giá trị cố định magpie; mọi giá trị đều được chấp nhận vì gateway mặc định lắng nghe trên loopback. Luôn chỉ định model theo định dạng provider/model.

Môi Trường Tương Thích Với OpenAI

export OPENAI_BASE_URL=http://127.0.0.1:3425/v1
export OPENAI_API_KEY=magpie

Môi Trường Tương Thích Với Anthropic

export ANTHROPIC_BASE_URL=http://127.0.0.1:3425
export ANTHROPIC_API_KEY=magpie

Môi Trường Tương Thích Với Gemini

export GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:3425
export GEMINI_API_KEY=magpie

Thẻ Gateway trong ứng dụng máy tính cung cấp các thiết lập và đoạn mã có thể sao chép cho shell, curl, Python và Node. Thẻ này cũng hiển thị mã định danh model và các lệnh gọi gần đây.

Làm Mới Danh Mục Model

Magpie lấy danh sách model thực từ các provider đã cấu hình. Danh mục models.dev cung cấp tên, cấp độ suy luận và danh sách dự phòng cho các provider không công bố danh mục riêng.

Chạy đồng bộ hóa đầy đủ khi bạn muốn làm mới dữ liệu models.dev và tất cả danh sách provider đang hoạt động:

magpie sync

Trong giao diện dòng lệnh, nhấn S để thực hiện thao tác tương tự. Bạn cũng có thể chỉ làm mới một nhà cung cấp bằng magpie provider models PROVIDER.

Nhập liên kết nhà cung cấp an toàn

Các nhà cung cấp và relay có thể phân phối các định nghĩa nhà cung cấp được điền sẵn bằng liên kết nhập. Magpie hiển thị tên nhà cung cấp, các endpoint, máy chủ đích và các mô hình được đề xuất trước khi lưu bất kỳ nội dung nào.

magpie import 'magpie://import?preset=deepseek&key=sk-…'

Một liên kết relay tùy chỉnh có thể bao gồm các endpoint OpenAI và Anthropic riêng biệt:

magpie://import?name=Acme%20Relay&chat=https://api.acme.example/v1&anthropic=https://api.acme.example&key=sk-…&models=gpt-5.5,claude-sonnet-5

Không có nội dung nào được lưu cho đến khi người dùng xác nhận việc nhập. Các trang web có thể sử dụng https://usemagpie.ai/import# theo sau là các tham số tương tự. Vì các giá trị vẫn nằm trong phần fragment của URL, trình duyệt không gửi chúng đến máy chủ của website. Xem hướng dẫn nhập Magpie để tham khảo đầy đủ các tham số và công cụ tạo liên kết.

Mẹo nâng cao

Giới hạn các mô hình được cung cấp

Bạn không cần cung cấp mọi mô hình mà nhà cung cấp trả về. Chỉ chọn những mô hình bạn muốn xuất hiện trong bộ chọn của tác nhân. Điều này giúp các danh mục lớn dễ quản lý hơn và hạn chế việc vô tình chọn sai mô hình.

Kiểm tra quá trình chuyển đổi của Gateway

Bật ghi nhật ký gỡ lỗi để xem gateway chuyển đổi những gì:

MAGPIE_DEBUG=1 magpie serve

Các yêu cầu được chuyển tiếp trực tiếp khi nhà cung cấp đã hỗ trợ API của bên gọi. Nếu không, Magpie sẽ chuyển đổi yêu cầu và phản hồi, đồng thời duy trì khả năng streaming, gọi công cụ và suy luận được hỗ trợ.

Biết dữ liệu được lưu ở đâu

• ~/.config/magpie/profiles.json lưu các hồ sơ đã lưu.
• ~/.config/magpie/providers.json lưu các nhà cung cấp và khóa của chúng với chế độ tệp 0600.
• ~/.config/magpie/stash.json lưu các giá trị đã được thay thế để có thể khôi phục.
• ~/.cache/magpie/models.json lưu danh mục models.dev.
• ~/.cache/magpie/models/<provider>.json lưu danh sách mô hình được lấy từ các nhà cung cấp.

Magpie hỗ trợ XDG_CONFIG_HOME và XDG_CACHE_HOME.

Sử dụng thư mục home phát triển biệt lập

Những người đóng góp có thể chạy bản dựng phát triển mà không ảnh hưởng đến cấu hình tác nhân thông thường:

HOME=/tmp/magpie-home XDG_CONFIG_HOME=/tmp/magpie-home/.config make dev

make dev cung cấp trực tiếp giao diện từ internal/gui/assets và tải lại giao diện khi các tệp frontend thay đổi. Gateway của nó sử dụng DEV_ADDR, mặc định là 127.0.0.1:3426, nên có thể chạy cùng với một phiên bản Magpie thông thường. Đặt MAGPIE_THEME=light hoặc MAGPIE_THEME=dark để buộc sử dụng một bảng màu.

Kết luận

Magpie thay thế việc cấu hình mô hình rời rạc bằng một quy trình nhất quán. Sau khi cài đặt, hãy thêm một nhà cung cấp hoặc sử dụng gói đăng ký tác nhân hiện có, chọn mô hình cho từng tác nhân và lưu các tổ hợp hữu ích thành hồ sơ. Gateway cục bộ của Magpie cũng cho phép các công cụ tương thích với OpenAI, Anthropic và Gemini khác dùng chung danh mục nhà cung cấp mà không cần lưu thông tin xác thực của nhà cung cấp trong từng ứng dụng.