03 / AI REPO RADAR

yetone/magpie

Ứng dụng kèm gateway cục bộ để đổi model cho từng coding agent (Claude Code, Codex, Gemini CLI...) từ một nơi, và tự chuyển sang tài khoản khác khi hết quota.

Magpie là gì và giải quyết vấn đề nào

Magpie là một ứng dụng chạy trên máy cá nhân, gom việc chọn model của nhiều coding agent về một chỗ. Khẩu hiệu của dự án là mỗi agent một model, tất cả trong một nơi. Ví dụ README nêu ra gồm Claude Code chạy trên Kimi, Codex chạy trên DeepSeek, Gemini CLI chạy trên GLM, và OpenCode chạy bằng gói ChatGPT của bạn. Việc chuyển đổi được thực hiện từ menu bar, còn phía sau là một gateway cục bộ phục vụ tất cả các agent.

Vấn đề mà README mô tả khá cụ thể: mỗi agent giữ model của nó trong một file riêng, theo định dạng riêng, với khóa API và địa chỉ gốc riêng. Một gói thuê bao bạn đã trả tiền chỉ dùng được trong một agent và không dùng được ở chỗ khác. Magpie đưa toàn bộ phần đó vào một ứng dụng và một gateway cục bộ, để bạn không còn phải mở từng file cấu hình ra sửa.

Theo README, dự án hứa ba việc. Thứ nhất, chọn bất kỳ model nào cho bất kỳ agent nào từ một danh sách chung, và Magpie chỉ sửa đúng một khóa quan trọng trong cấu hình của agent đó. Thứ hai, dùng một nhà cung cấp ở mọi nơi, dù đó là khóa API, một model chạy cục bộ, hay gói Claude, ChatGPT, Copilot, Gemini hoặc Grok mà bạn đang đăng nhập. Thứ ba, tiếp tục làm việc khi hết quota: một routing group sẽ chuyển sang tài khoản hoặc model kế tiếp và agent không nhìn thấy lỗi.

Cách hoạt động: một gateway cục bộ làm cầu nối

Trung tâm của thiết kế là gateway chạy trên địa chỉ cục bộ, cổng 3425. README cho biết gateway này nói được bốn giao thức: OpenAI Chat, OpenAI Responses, Anthropic Messages và Gemini, đồng thời dịch qua lại giữa chúng, bao gồm cả streaming, tool call và phần reasoning. Nhờ đó một agent vốn chỉ biết một giao thức vẫn có thể dùng model của nhà cung cấp nói giao thức khác.

Khi bạn chọn model cho một agent, Magpie ghi lại cấu hình của agent đó theo kiểu atomic, nghĩa là ghi trọn vẹn hoặc không ghi, và README nói rõ phần chú thích, thứ tự và định dạng trong file được giữ nguyên. Đây là chi tiết đáng chú ý với người hay tự chỉnh file cấu hình, vì công cụ không làm xáo trộn những gì họ đã viết.

Với những ứng dụng không nằm trong danh sách hỗ trợ, README cho biết bất cứ thứ gì nhận một địa chỉ gốc đều có thể dùng gateway. README không nêu chi tiết cách thiết lập cho trường hợp này trong phần giới thiệu, mà chỉ trỏ tới tài liệu tham khảo, nên bạn cần đọc thêm tài liệu của dự án khi cần.

Chọn model cho từng agent, hồ sơ và nhà cung cấp

Trên trang Agents, bạn bấm vào một giá trị và một danh sách có ô tìm kiếm mở ra. Danh sách này liệt kê mọi model của mọi nhà cung cấp bạn đã thêm, theo dạng nhà cung cấp rồi model. README còn nói thêm về Profiles: bạn lưu cấu hình của toàn bộ agent dưới một cái tên như Budget hay Focus, rồi chuyển tất cả về cấu hình đó chỉ bằng một thao tác. Mỗi agent cũng có thể có danh sách ngắn các model riêng, và một profile giữ cả danh sách này.

Về nhà cung cấp, bạn chọn một preset rồi dán khóa vào. Danh sách model được lấy từ chính nhà cung cấp, còn tên và mức reasoning được điền từ nguồn dữ liệu models.dev, nên theo README một model mới ra sáng nay sẽ có trong bộ chọn ở lần làm mới kế tiếp. Các preset được liệt kê gồm Anthropic, OpenAI, Google Gemini, Google Vertex AI, Amazon Bedrock, DeepSeek, Kimi, Zhipu GLM, MiniMax, Qwen, Mistral, Groq, xAI, OpenRouter, Together, Fireworks, NVIDIA NIM, Ollama và LM Studio, cùng nhiều tên khác, và bất kỳ địa chỉ nào tương thích với OpenAI hoặc Anthropic.

Nếu bạn đã có cấu hình ở nơi khác, tính năng Import có thể nhập nhà cung cấp từ CC Switch, Claude Code, Codex và Alma. Ngoài ra có các liên kết Add to magpie để trang web của một nhà cung cấp trao cấu hình cho Magpie chỉ bằng một cú nhấp. Mỗi khóa và mỗi tài khoản còn có thể đi qua một proxy riêng.

Gói thuê bao được coi như nhà cung cấp

Một ý tưởng trung tâm khác là coi gói thuê bao như một nhà cung cấp. Theo README, một agent mà bạn đã đăng nhập chính là một gói thuê bao có các model đứng sau, và Magpie đưa nó ra như một nhà cung cấp cho mọi agent khác. Bạn có thể thêm nhiều tài khoản cho cùng một gói, và Magpie sẽ chuyển dự phòng giữa chúng.

Danh sách trong README gồm Claude, nơi Magpie điều khiển chính tiến trình claude cục bộ và bắc cầu các công cụ của agent qua MCP; Codex và ChatGPT, để dùng model của gói ChatGPT trong mọi agent khác; cùng GitHub Copilot, Gemini qua Code Assist, Antigravity, Grok qua SuperGrok và một số gói khác. Ngoài ra còn hỗ trợ bất kỳ plugin xác thực của OpenCode hoặc gói pi nào lấy từ npm.

Có một tính năng nhỏ nhưng thực tế gọi là Daily warm-up. Nó khởi động cửa sổ 5 giờ của từng tài khoản Claude và ChatGPT vào những thời điểm bạn chọn, hoặc ngay khi cửa sổ cuối cùng được đặt lại. README không giải thích sâu hơn về lý do, nên bạn nên hiểu đây là cách để cửa sổ quota bắt đầu tính giờ đúng lúc bạn muốn.

Routing group: phân phối yêu cầu và chuyển dự phòng

Routing group là nhóm nhiều model mà agent chọn như một, chẳng hạn group/daily-coding. Gateway trải các yêu cầu ra mọi khóa và tài khoản của từng thành viên trong nhóm. README liệt kê năm chế độ. Chế độ smart chọn gói thuê bao còn quota và sắp được làm mới sớm nhất, để ít bị lãng phí khi đặt lại. Chế độ order dùng model đầu tiên cho đến khi nó không trả lời được thì sang model kế. Chế độ rotate chuyển sang thành viên tiếp theo ở mỗi lượt. Chế độ usage dùng thành viên ít được dùng nhất trước. Chế độ pace dùng tài khoản còn nhiều thời gian của tuần nhất theo từng giờ, cho đến khi nó được đặt lại.

README nhấn mạnh rằng một cuộc hội thoại ở lại với tài khoản đã trả lời nó chừng nào bộ nhớ đệm prompt của nhà cung cấp còn đáng giữ. Các nhóm có thể chứa các nhóm khác. Đây là chi tiết quan trọng với người dùng coding agent, vì chuyển tài khoản giữa chừng có thể làm mất lợi ích của prompt cache.

Ngoài ra còn có Intent routing: một model nhỏ do bạn chọn đọc từng lượt mới, để các bài kiểm thử đi tới model mạnh còn câu hỏi nhanh đi tới model rẻ. Màn hình Routing hiển thị mọi quyết định định tuyến theo thời gian thực. README không công bố số liệu độ chính xác của cách phân loại này, nên hiệu quả thực tế cần bạn tự đánh giá trên khối lượng công việc của mình.

Plugin và middleware cho gateway

Plugin chạy trên Bun, được tải về ở lần đầu một plugin cần đến. Theo README, một plugin đăng nhập, liệt kê model và thực hiện từng yêu cầu, còn các agent dùng những model đó như của mọi nhà cung cấp khác. Bạn có thể duyệt kho plugin cộng đồng hoặc tự viết plugin cho riêng mình.

Một plugin cũng có thể là middleware của gateway: đoạn JavaScript nhìn thấy mọi thứ các agent gửi đi và nhận về. Hook onRequest có thể viết lại hoặc từ chối một yêu cầu, onEvent thấy từng sự kiện được stream, và onResponse thấy toàn bộ phản hồi. README nêu một điểm an toàn: nếu một hook ném lỗi hoặc chạy quá lâu, yêu cầu được giữ nguyên như ban đầu.

Các gói middleware dựng sẵn gồm param-override để đặt, xóa, di chuyển hoặc viết lại trường của yêu cầu theo điều kiện; model-map để gửi một model dưới tên khác; system-prompt để chèn system prompt của bạn vào mọi yêu cầu hoặc chỉ vào một số agent; word-guard để từ chối hoặc che các từ nhạy cảm; và think-tags để gỡ hoặc thêm phần reasoning trong phản hồi. README cho biết phần lớn trong số này tái hiện những gì New API làm cho các kênh của nó, với cùng định dạng JSON.

Theo dõi chi phí, chia sẻ và các tính năng đi kèm

Phần Usage and cost theo dõi token, lượt đọc và ghi cache, reasoning và số lượt gọi, kèm chi phí tính theo giá niêm yết bằng đô la hoặc nhân dân tệ, và bạn có thể đặt giá riêng cho bất kỳ model nào. Phần Quota cho thấy số dư và cửa sổ quota của từng khóa, gói và tài khoản, cùng lời nhắc trước khi một cửa sổ được làm mới trong khi còn nhiều quota chưa dùng. Ngoài ra có Sessions để mở lại từng cuộc hội thoại trong terminal, Context cho biết cửa sổ ngữ cảnh đầy đến đâu, và Bills theo tài khoản, theo khóa upstream, cùng khả năng xuất OTLP sang hệ thống quan sát của riêng bạn.

Về chia sẻ, bạn có thể bật chia sẻ trên mạng nội bộ và cấp cho mỗi máy khách một khóa gateway có tên cùng giới hạn token và chi phí theo ngày, tuần hoặc tháng. Chế độ Remote magpie cho phép một máy xách tay dùng nhà cung cấp, tài khoản và nhóm của Magpie trên máy để bàn. Bản Docker chạy trên máy chủ hoặc NAS và được quản lý bằng giao diện web. Bạn cũng có thể sao lưu ra file hoặc đồng bộ giữa các máy qua WebDAV, S3 hoặc một bản sao lưu mã hóa trên kho GitHub.

Thêm vào đó, README nhắc tới Library, nơi bạn viết một lần các chỉ dẫn, MCP server, skill và subagent, rồi Magpie ghi chúng vào file của từng agent theo định dạng riêng và chỉ gỡ đúng những gì nó đã ghi. Ngoài ra có tìm kiếm web cho model không biết tìm, công cụ tạo ảnh qua MCP, tự cập nhật phiên bản các agent, và hỗ trợ agent bên trong WSL trên Windows.

Cài đặt và dùng thử

Theo README, Magpie chạy trên macOS, Windows và Linux dưới dạng ứng dụng menu bar, cửa sổ, giao diện TUI, giao diện web hoặc dòng lệnh, và còn chạy trong Docker hoặc trên Termux. Bản dựng cho Mac được ký và công chứng, và mọi bản dựng tự cập nhật. Nếu đứng sau tường lửa, bạn dùng tùy chọn proxy hoặc mirror. Cách khác là cài bằng go install hoặc dùng ảnh Docker.

Quy trình bắt đầu gồm ba bước. Bước một là cài ứng dụng. Bước hai là vào Providers rồi Add provider, chọn một preset và dán khóa, hoặc đăng nhập bằng gói thuê bao. Bước ba là chọn model cho từng agent ở trang Agents; phiên mới bắt đầu sẽ chạy trên model mới. README cũng cho biết mọi thao tác này làm được từ terminal, nhưng phần lệnh cụ thể không có trong bản nguồn mà chúng tôi đọc, nên bài này không mô tả chúng.

Danh sách agent được hỗ trợ rất dài, gồm Claude Code, Codex, Gemini CLI, OpenCode, Goose, Cursor CLI, Zed, Copilot CLI, Cline, Qwen Code, Droid và nhiều công cụ khác. Magpie chỉ hiển thị những agent đang được cài trên máy của bạn.

Quyền riêng tư, giới hạn và điều cần lưu ý

Magpie tìm các gói thuê bao mà agent của bạn đã đăng nhập bằng cách đọc thông tin đăng nhập của chúng, gồm file của Claude Code và Codex và Keychain. Đây là điểm nhạy cảm cần biết trước khi dùng. Bạn có thể tắt trong Settings, Privacy, mục Subscription accounts, hoặc chạy lệnh tắt khám phá tài khoản, hoặc đặt biến môi trường MAGPIE_NO_ACCOUNTS bằng 1 cho một lần chạy. Các nhà cung cấp dùng khóa API vẫn hoạt động khi tắt.

README nói prompt, phản hồi, khóa và tài khoản của bạn chỉ đi tới những nhà cung cấp bạn dùng. Mỗi ngày một bản phát hành của Magpie báo cho tác giả rằng nó đang được dùng, kèm một mã ngẫu nhiên, phiên bản, hệ thống, và các agent, nhà cung cấp, model đang dùng theo mã riêng của Magpie. README khẳng định không gửi tên, URL, tài khoản, khóa, prompt hay dữ liệu sử dụng. Bạn có thể tắt một phần hoặc toàn bộ trong Settings, Privacy, hoặc bằng DO_NOT_TRACK bằng 1. Đây là mô tả do tác giả tự công bố và chúng tôi không kiểm chứng.

Một giới hạn khác về đóng góp: README nêu rõ kho mã không nhận pull request, chỉ người bảo trì mới được mở. Muốn sửa lỗi hay thêm tính năng, bạn mô tả trên Discord. Điều này khác với nhiều dự án mã nguồn mở thông thường, nên đừng kỳ vọng đóng góp trực tiếp. README cũng không đề cập phần kiến trúc bên trong, cách kiểm thử hay hiệu năng của gateway, vì vậy bài này không đưa ra nhận định về những điểm đó.

Khi nào nên và không nên dùng

README tự nói rõ đối tượng phù hợp: người dùng nhiều hơn một agent, nhiều hơn một nhà cung cấp, hoặc nhiều hơn một tài khoản. Nếu bạn chỉ dùng một agent trên gói của chính nhà cung cấp và thấy đủ, bạn không cần đến Magpie. Chúng tôi đồng ý với cách đặt vấn đề này, vì giá trị của công cụ nằm ở việc gom cấu hình rải rác.

Với người xây AI agent, Magpie hữu ích ở chỗ cho phép thử cùng một agent trên nhiều model khác nhau mà không đụng tới cấu hình thủ công, đồng thời có số liệu chi phí và quota để so sánh. Routing group và intent routing phù hợp khi bạn muốn tiết kiệm bằng cách đưa tác vụ nhẹ sang model rẻ. Middleware cho phép áp một system prompt hay quy tắc lọc chung cho nhiều agent cùng lúc.

Cần thận trọng khi dùng một công cụ đọc thông tin đăng nhập của các agent khác và đứng giữa mọi yêu cầu. Hãy xem kỹ cài đặt riêng tư, cân nhắc việc dùng plugin của bên thứ ba có thể thấy toàn bộ prompt, và đọc điều khoản của từng nhà cung cấp về việc dùng chung gói thuê bao giữa nhiều công cụ. README không bàn đến các điều khoản đó. Các con số về stars, tăng trưởng 7 ngày và giấy phép MIT trong bài lấy từ metadata của kho mã, hiện là 20.274 sao với mức tăng 5.278 trong 7 ngày.

Bài do AI viết tự động từ README và dữ liệu GitHub API của repo, có kiểm tra tự động nhưng không có người duyệt từng câu. Báo sai sót qua email.