omp (Oh My Pi) + JoinGonka Gateway: agent với vai trò mô hình

Bước 1: cài omp. Các cách chính thức từ README của dự án:

# macOS and Linux
curl -fsSL https://omp.sh/install | sh

# Homebrew
brew install can1357/tap/omp

# via Bun (requires Bun 1.3.14 or newer)
bun install -g @oh-my-pi/pi-coding-agent

# Windows (PowerShell)
irm https://omp.sh/install.ps1 | iex

Bước 2: lấy key. Đăng ký tại gate.joingonka.ai/register, xác nhận địa chỉ và tạo key với tiền tố jg- trong mục «API key». Một key và một số dư dùng chung cho tất cả các model của mạng.

Bước 3: chạy trình cài đặt.

npx @joingonka/setup --tool omp

Trình cài đặt sẽ hỏi key — key không được truyền qua tham số dòng lệnh để tránh lưu lại trong lịch sử shell — và thực hiện bốn việc:

• ghi nhà cung cấp joingonka vào ~/.omp/agent/models.yml: địa chỉ gateway, giao thức openai-completions, key dạng literal và ba model của mạng với cửa sổ ngữ cảnh và giới hạn phản hồi thực; file sẽ có quyền 600;
• đặt model mặc định — modelRoles.default trong ~/.omp/agent/config.yml — thành DeepSeek V4 Flash, nhưng chỉ khi vai trò đó trống hoặc trỏ đến một model đã rời khỏi mạng: nó không ghi đè lựa chọn của bạn mà chỉ gợi ý cách chuyển đổi;
• sao lưu file cũ trước khi ghi, và giữ nguyên các nhà cung cấp, vai trò và chú thích khác;
• cuối cùng gửi một yêu cầu trực tiếp đến gateway và cho biết rõ key, địa chỉ và model có được chấp nhận hay không.

Để đặt model mặc định khác, dùng flag --model với viết tắt deepseek, glm hoặc minimax — model được chỉ định rõ ràng luôn được ghi. Đối với dotfile và máy chủ, có chế độ không hỏi đáp, trong đó key được lấy từ biến môi trường:

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool omp --model glm --non-interactive

Trình cài đặt tự xử lý vị trí cấu hình không chuẩn: profile có tên (OMP_PROFILE) và thư mục agent đã di chuyển (PI_CODING_AGENT_DIR). Nó di chuyển models.json kế thừa sang models.yml giống như chính omp sẽ làm — các nhà cung cấp cũ không bị mất. Và nếu bên cạnh có settings.json cũ mà không có config.yml, trình cài đặt sẽ không tạo config.yml để omp không bỏ qua việc tự di chuyển cài đặt của nó: nó sẽ yêu cầu bạn chạy omp một lần rồi lặp lại lệnh.

Mọi thứ mà trình cài đặt thực hiện đều có thể viết tay. Chỉ có hai tệp, mỗi tệp đảm nhiệm một việc: models.yml mô tả các nhà cung cấp và mô hình, config.yml lưu cấu hình — trong đó có việc mô hình nào đảm nhiệm vai trò nào.

# ~/.omp/agent/models.yml
providers:
  joingonka:
    baseUrl: https://gate.joingonka.ai/v1
    api: openai-completions
    apiKey: jg-your-key
    models:
      - id: deepseek-ai/DeepSeek-V4-Flash-0731
        name: DeepSeek V4 Flash (Gonka)
        input: [text]
        contextWindow: 380000
        maxTokens: 32768
        reasoning: true
      - id: zai-org/GLM-5.3-Flash
        name: GLM-5.3 Flash (Gonka)
        input: [text]
        contextWindow: 390000
        maxTokens: 8192
        reasoning: true
      - id: MiniMaxAI/MiniMax-M2.7
        name: MiniMax M2.7 (Gonka)
        input: [text]
        contextWindow: 200000
        maxTokens: 8192

# ~/.omp/agent/config.yml
modelRoles:
  default: joingonka/deepseek-ai/DeepSeek-V4-Flash-0731

Dùng khóa trực tiếp là phương án ít rắc rối nhất: omp khởi động được từ mọi môi trường, chỉ cần đóng quyền tệp bằng lệnh chmod 600 ~/.omp/agent/models.yml. Muốn giữ khóa ngoài tệp — hãy ghi tên biến vào apiKey, ví dụ JOINGONKA_API_KEY, rồi export nó trong shell mà bạn chạy omp: đúng trình tự phân giải khóa này được mô tả trong tài liệu dự án.

Trường tùy chọn cost (giá trên một triệu token) chỉ cần thiết để ước tính chi phí phiên trong giao diện omp. Trình cài đặt ghi vào đó mức giá thực tế của cổng tại thời điểm cài; trong cấu hình thủ công có thể bỏ qua trường này — ước tính đó không liên quan đến hóa đơn của bạn, mức tiêu thụ thực tế được hiển thị trong trang quản lý.

Bộ chọn mô hình được ghi dưới dạng provider/model-id. Tên nhà cung cấp được tách theo dấu gạch chéo đầu tiên, vì vậy các ID của mạng lưới có dấu gạch chéo riêng được ghi nguyên như vậy: joingonka/deepseek-ai/DeepSeek-V4-Flash-0731. Thay vì sửa config.yml, có thể gán vai trò ngay từ giao diện — bằng lệnh /model trong phiên hoặc trong trình hướng dẫn omp setup.

Trong omp, bạn không chỉ chọn một mô hình cho mọi thứ, mà chọn theo vai trò — đây chính là đòn bẩy cấu hình chính. Các vai trò tích hợp cho đối thoại bao gồm: default, smol, slow, plan, commit, task, tiny, memory, advisor và vision. Bạn không cần chỉ định tất cả: các vai trò smol và slow không được đặt sẽ lấy mô hình của vai trò default, các tác nhân phụ không có vai trò task sẽ hoạt động trên mô hình của phiên hiện tại, commit và tiny sẽ theo sau smol. Cấu hình chỉ với một dòng default là hoàn toàn có thể hoạt động.

Việc phân chia các vai trò giữa các mô hình mạng không phải để tiết kiệm chi phí — vì giá của DeepSeek V4 Flash, GLM-5.3 Flash và MiniMax M2.7 là như nhau — mà là vì hành vi và công suất: một mô hình suy luận tốt hơn trong việc lập kế hoạch, mô hình có phản hồi dài tốt hơn trong việc viết lách, và các tác vụ nền không cần thiết phải xếp hàng cùng với nhiệm vụ chính.

# ~/.omp/agent/config.yml
modelRoles:
  default: joingonka/deepseek-ai/DeepSeek-V4-Flash-0731
  slow: joingonka/zai-org/GLM-5.3-Flash
  plan: joingonka/zai-org/GLM-5.3-Flash
  tiny: joingonka/MiniMaxAI/MiniMax-M2.7

retry:
  fallbackChains:
    default:
      - joingonka/zai-org/GLM-5.3-Flash

Khối retry.fallbackChains — là biện pháp bảo hiểm cho giờ cao điểm: khi mô hình chính liên tục trả về 429, omp chuyển phần còn lại của lượt cho mục tiếp theo trong chuỗi, và sau khi tạm dừng sẽ quay lại mô hình chính. Khóa của chuỗi có thể là vai trò, mô hình cụ thể hoặc toàn bộ nhà cung cấp (joingonka/*).

Đối với một lần khởi chạy, vai trò được định nghĩa lại bằng cờ: omp --model slow khởi chạy phiên trên mô hình vai trò slow, trong khi --smol, --slow và --plan thay thế mô hình của chính vai trò đó. Trong phiên làm việc, Ctrl+P cuộn qua các mô hình vai trò, và /model mở trình chọn; trong tab Roles tại đó, bạn có thể chỉ định vai trò và các lựa chọn dự phòng của chúng.

Bạn có thể thêm mức độ suy luận vào giá trị vai trò — :low, :medium, :high. Đây là cú pháp của omp, còn việc mô hình cụ thể hiểu mức độ đó như thế nào thì phụ thuộc vào chính mô hình đó: ví dụ với GLM-5.3 Flash, đây là một bộ chuyển đổi nhị phân — chi tiết có trong đánh giá mô hình. Và một chi tiết hữu ích khác: các vai trò có thể được định nghĩa lại cho một kho lưu trữ bằng tệp <repo>/.omp/config.yml với cùng khối modelRoles. Các nhà cung cấp và khóa khi đó vẫn ở trong thư mục chính, vì vậy khóa sẽ không lọt vào kho lưu trữ.

Trước tiên, hãy đảm bảo rằng omp nhận diện được nhà cung cấp:

omp models joingonka

Kết quả trả về là một bảng gồm ba dòng với cửa sổ ngữ cảnh và giới hạn phản hồi lấy từ models.yml, được làm tròn đến hàng nghìn (output đã lược bớt: omp còn có thêm các cột thinking và images):

joingonka (3)
model                                context  max-out
deepseek-ai/DeepSeek-V4-Flash-0731      380K      33K
MiniMaxAI/MiniMax-M2.7                  200K     8.2K
zai-org/GLM-5.3-Flash                   390K     8.2K

Tiếp theo là một lần chạy thử không giao diện. Hãy đặt vào một thư mục trống một tệp có lỗi rõ ràng và yêu cầu tìm ra lỗi đó:

omp -p "Read calc.py and tell me in one sentence whether it has a bug."

Agent phải tự gọi công cụ đọc tệp và trả lời đúng trọng tâm — kèm theo biểu thức chứa lỗi. Trong lần chạy thử ngày 21 tháng 9 năm 2026 của chúng tôi, vòng lặp này — yêu cầu, gọi công cụ, kết quả, phản hồi — đã diễn ra trơn tru với DeepSeek V4 Flash và GLM-5.3 Flash; còn về MiniMax M2.7 — xem dòng cuối bảng bên dưới.

Kiểm tra thứ ba — từ phía gateway: trong bảng điều khiển ở mục "Sử dụng", yêu cầu sẽ xuất hiện trong phần phân tách "Theo mô hình", và trong khối "Theo khóa", thời gian yêu cầu cuối cùng sẽ được cập nhật. Nếu ở đó trống, nghĩa là omp đang gọi một nhà cung cấp khác: hãy xem cấu hình vai trò bằng lệnh omp config get modelRoles.

Nếu có sự cố xảy ra, chẩn đoán thường đọc được ngay từ thông báo:

Công cụ đại lý tiêu tốn token khác với trò chuyện: với mỗi câu lệnh của bạn, omp thêm vào prompt hệ thống và mô tả các công cụ, và một tác vụ thường mất vài lượt. Trong thử nghiệm của chúng tôi, ngay cả với chỉ một công cụ đọc được bật, mỗi lượt đã tiêu tốn khoảng 3,5 nghìn token đầu vào; với bộ công cụ đầy đủ, con số sẽ còn cao hơn. Do đó, chi phí cho mỗi token ở đây là yếu tố quyết định.

Thông qua JoinGonka Gateway, token có giá $0.0069 mỗi triệu token đầu vào và $0.021 mỗi triệu token đầu ra — giá cả giống nhau cho tất cả các mô hình trong mạng lưới và được cập nhật trên trang này từ nguồn trực tiếp.

Các ước tính trong cột bên phải dựa trên giá tháng 9 năm 2026. Để so sánh — cách bạn có thể thanh toán cho các mô hình trong omp:

Dòng trạng thái của omp hiển thị ước tính chi phí phiên làm việc. Nó được tính dựa trên trường cost trong models.yml: trình cài đặt ghi giá cổng vào đó tại thời điểm cài đặt, và giá bằng đô la trong mạng lưới biến động cùng với tỷ giá GNK, vì vậy ước tính chỉ mang tính tham khảo. Mức tiêu thụ chính xác và số dư còn lại — trong bảng điều khiển, tại các mục "Sử dụng" và "Thanh toán". Tại sao lựa chọn mặc định lại là DeepSeek V4 Flash, đã được giải thích chi tiết trong đánh giá mô hình.

Chế độ phê duyệt. Mặc định omp chạy ở chế độ yolo: tự động phê duyệt việc đọc, ghi và chạy lệnh. Trên dự án của bạn thì tiện, nhưng với code của người khác thì nên siết chặt chế độ hoặc chuyển vào container:

omp config set tools.approvalMode write

Ở chế độ write, agent chỉ hỏi quyền khi thực thi lệnh; ở always-ask thì hỏi cả khi ghi. Với một lần chạy, cờ --approval-mode cũng đặt được tương tự. Đây là thuộc tính của chính omp, không phụ thuộc vào nhà cung cấp model.

Pi và omp là họ hàng nhưng cấu hình khác nhau. Cấu hình của công cụ này không truyền sang công cụ kia: thư mục, định dạng và tên trường của chúng đều riêng.

Nhiều môi trường. Profile có tên (omp --profile work hoặc biến OMP_PROFILE) chuyển toàn bộ cấu hình vào ~/.omp/profiles/<name>/agent — tiện để tách khóa công việc và cá nhân. Thư mục agent hiện tại in ra bằng omp config path.

Nếu cần agent trong editor. omp chạy được trong Zed qua giao thức ACP — vẫn là agent đó với đúng cấu hình đó, không cần khai báo lại nhà cung cấp và vai trò.