DeepSeek Harness: nhà cung cấp của riêng bạn thông qua JoinGonka Gateway

Harness là tất cả những gì bao quanh model trong công việc agent: vòng lặp «yêu cầu → gọi công cụ → kết quả → bước tiếp theo», các công cụ cho tệp và terminal, quyền hạn và xác nhận, nhật ký phiên, nén ngữ cảnh. DeepSeek Harness ghép những thứ này từ các plugin: kiến trúc «everything is a plugin» được xây trên framework Cordis, cho phép thay thế bất kỳ thành phần nào — từ công cụ đến adapter model — mà không cần sửa lõi. Mã nguồn mở theo giấy phép MIT.

Không cần cài đặt — chỉ cần Node.js (dòng 22 từ 22.19 trở lên, hoặc 24 và mới hơn):

npx @deepseek-ai/dsh web

Lệnh này khởi động Web UI tại http://127.0.0.1:3080 và tự mở trong trình duyệt; khi chạy qua SSH, địa chỉ chỉ được in ra trong terminal. Cờ --no-open chạy server mà không mở trình duyệt, --port đổi cổng. Thư mục mà dsh được khởi chạy từ đó sẽ trở thành thư mục làm việc mặc định, nhưng giao diện chỉ bắt đầu phiên sau khi workspace được chọn rõ ràng.

Tầng model gồm hai adapter. Adapter trực tiếp đi thẳng vào API chính thức của nhà cung cấp. Adapter đa nhà cung cấp — dsh-llm-pi-ai — được xây trên thư viện pi-ai, cùng thư viện làm nền cho terminal agent Pi; qua đó có thể kết nối cả các nhà cung cấp tích hợp sẵn trong danh mục lẫn bất kỳ endpoint riêng nào. Vì vậy, tên các trường trong cấu hình — api, contextWindow, maxTokens — trùng khớp với những gì bạn đã quen từ Pi.

Về độ chín muồi. README của dự án mở đầu bằng cảnh báo: developer preview, vòng lặp phát triển nhanh, có thể có thay đổi phá vỡ tương thích. Tài liệu SAFETY.md riêng nói rõ rằng chưa từng có đánh giá bảo mật, và agent thực thi các lệnh do model sinh ra. Kết luận thực tế rất đơn giản: hãy chạy dsh trong container, máy ảo hoặc dưới một tài khoản riêng, và luôn sao lưu mọi thứ mà nó có thể chạm tới.

Bước 1: lấy API key. Đăng ký tại gate.joingonka.ai/register: sau khi xác nhận địa chỉ, tài khoản của bạn sẽ được cộng 3M token miễn phí. Trong bảng điều khiển, mở mục "API key" và tạo một key có tiền tố jg-. Nên tạo riêng một key cho harness — như vậy lưu lượng của nó sẽ hiển thị thành một dòng riêng trong thống kê.

Bước 2: màn hình đầu tiên. Sau thông báo về trạng thái thử nghiệm (nút Continue), dsh sẽ yêu cầu bạn nhập key của API chính thức ("Add an API key to get started"). Bước này không bắt buộc: hãy nhấn Configure later.

Bước 3: nhà cung cấp. Mở Settings → Models và chọn Add a custom provider. Các trường trong biểu mẫu:

Bước 4: các model. Trong khối Models, nhấn Fetch available models: dsh sẽ truy vấn danh sách từ gateway và mở cửa sổ "Choose models to add". Trong lần chạy thử của chúng tôi, cửa sổ này hiển thị cả ba model của mạng lưới — MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731 và zai-org/GLM-5.3-Flash — và sau khi nhấn Add selected, harness tự động gán cho mỗi model cửa sổ ngữ cảnh và giới hạn phản hồi theo dữ liệu từ gateway. Việc còn lại chỉ là nhấn Create provider.

Bước 5: chọn model. Đóng phần cài đặt, nhấn Choose workspace và thêm thư mục dự án. Các model của nhà cung cấp mới sẽ xuất hiện trong trình chọn; model được chọn sẽ trở thành model mặc định cho các phiên mới.

dsh lưu key tách biệt khỏi phần cài đặt: trong tệp ~/.dsh/.credentials.yaml với quyền chỉ dành cho chủ sở hữu. Trong settings.yaml chỉ còn lại tên tham chiếu đến nó — trong lần chạy thử của chúng tôi là JOINGONKA_API_KEY, theo định danh của nhà cung cấp.

Nên chọn giao thức nào. Gateway hỗ trợ cả ba giao thức; khác nhau ở địa chỉ cơ sở và những tiện ích đi kèm:

Mỗi nhà cung cấp trong dsh chỉ nói một giao thức, vì vậy giao thức thứ hai đồng nghĩa với nhà cung cấp thứ hai với Provider ID khác. Với công việc hằng ngày, lựa chọn đầu tiên là đủ; trong lần chạy thử của chúng tôi, vòng lặp agent có gọi công cụ đã hoạt động với cả ba giao thức.

Form Models ghi vào một tài liệu YAML thông thường — $DSH_HOME/settings.yaml, mặc định là ~/.dsh/settings.yaml. Bạn có thể chỉnh sửa trực tiếp: nút Open configuration file ở đầu trang cài đặt sẽ mở tệp, và các adapter sẽ đọc lại tệp trong lần yêu cầu tiếp theo — không cần khởi động lại. Đây là cấu hình đầy đủ cho mạng Gonka:

# ~/.dsh/settings.yaml
llm-pi-ai:
  providers:
    joingonka:
      displayName: JoinGonka Gateway
      apiKeyEnv: JOINGONKA_API_KEY
      api: openai-completions
      baseURL: https://gate.joingonka.ai/v1
      models:
        - id: deepseek-ai/DeepSeek-V4-Flash-0731
          name: DeepSeek V4 Flash
          contextWindow: 380000
          maxTokens: 32768
        - id: zai-org/GLM-5.3-Flash
          name: GLM-5.3 Flash
          contextWindow: 390000
          maxTokens: 8192
          reasoningEfforts:
            off: low
            high: high
        - id: MiniMaxAI/MiniMax-M2.7
          name: MiniMax M2.7
          contextWindow: 200000
          maxTokens: 8192
agent-default-model:
  provider: joingonka
  model: deepseek-ai/DeepSeek-V4-Flash-0731

Những điểm quan trọng ở đây:

• apiKeyEnv — không phải là khóa mà là tên tham chiếu đến khóa. dsh tìm giá trị theo thứ tự: biến môi trường tại thời điểm khởi chạy, sau đó .credentials.yaml (nơi form ghi vào), tiếp theo .env trong thư mục khởi chạy, cuối cùng là ~/.dsh/.env. Nếu bạn thiết lập harness không có trình duyệt, chỉ cần dòng JOINGONKA_API_KEY=jg-your-key trong ~/.dsh/.env với quyền 600. Biến được export sau khi khởi động sẽ không được tiến trình đang chạy nhìn thấy.
• Hãy khai báo rõ ràng contextWindow và maxTokens. Với model mà dsh không biết, nó gán mặc định 262 144 và 32 768 token — không khớp với giới hạn thực tế. maxTokens được đặt cũng trở thành giới hạn phản hồi mặc định cho mỗi yêu cầu.
• reasoningEfforts — các mức suy luận cho menu Effort. Với model được nhập thủ công, không có mức nào, và menu cho nó sẽ không xuất hiện. Với GLM-5.3 Flash, công tắc là nhị phân: giá trị low tắt suy luận, bất kỳ giá trị nào khác giữ nguyên suy luận đầy đủ. Vì vậy mức off được ánh xạ thành low, còn high được giữ nguyên. Trong lần chạy thử của chúng tôi với off hoàn toàn không có khối suy luận nào, với high chúng quay trở lại.
• agent-default-model — model cho các agent mới, bao gồm cả chế độ headless. Việc chọn model trong giao diện cũng làm điều tương tự; ở đây cũng có thể thêm reasoningEffort.

Các công tắc compat mà tài liệu dsh khuyến nghị cho các gateway nghiêm ngặt (supportsDeveloperRole: false, maxTokensField: max_tokens) ở đây không cần thiết: JoinGonka Gateway chấp nhận cả vai trò developer và trường max_completion_tokens.

Trình cài đặt npx @joingonka/setup không thiết lập harness này: toàn bộ việc kết nối chỉ gói gọn trong form ở phần trước hoặc đoạn YAML ở trên.

Cách nhanh nhất để kiểm tra kết nối là chạy thử một lần từ thư mục chứa mã nguồn. Hãy đặt bên cạnh một tệp nhỏ có lỗi rõ ràng và yêu cầu tìm ra lỗi đó:

cd /path/to/project
npx @deepseek-ai/dsh --profile headless "Read calc.py and tell me in one sentence whether it has a bug."

Câu trả lời cuối cùng được in ra stdout, quá trình suy luận — ra stderr với nhãn dsh: reasoning:. Tác nhân phải tự gọi công cụ đọc tệp và trả lời đúng trọng tâm: trong lần chạy của chúng tôi, cả ba mô hình của mạng đều chỉ ra dòng bị lỗi. Nghĩa là toàn bộ chu trình «yêu cầu → gọi công cụ → kết quả → phản hồi» qua cổng đã được lắp ghép chính xác.

Nửa còn lại của phép kiểm tra nằm ở phía cổng. Trong bảng điều khiển, hãy mở «Sử dụng»: tại đó có thể thấy các yêu cầu theo giờ và theo ngày, phân tách theo mô hình và theo khóa. Xuất hiện một dòng với khóa của harness và thời gian yêu cầu gần nhất mới — lưu lượng thực sự đang đi qua cổng.

Nếu có gì đó không ổn, chẩn đoán thường đọc được ngay từ thông báo:

Giá của tất cả các mô hình trong mạng là như nhau, vì vậy việc lựa chọn phụ thuộc vào hành vi thay vì ngân sách. Dưới đây là các giới hạn và cách các mô hình hoạt động trong quá trình chạy thử nghiệm dsh của chúng tôi trên cùng một tác vụ: đọc một tệp và tìm lỗi trong đó.

Khuyến nghị mặc định là DeepSeek V4 Flash: công việc đại lý thường nhanh chóng chạm ngưỡng về dung lượng ngữ cảnh và độ dài sửa đổi, trong khi mô hình này có dư địa cho cả hai tham số. Khi tác vụ yêu cầu tư duy về logic phức tạp, hãy chuyển sang GLM-5.3 Flash và đặt mức lập luận high; để sửa đổi nhanh, cùng nhà cung cấp đó sẽ đưa ra kết quả với mức off. MiniMax M2.7 là một lựa chọn ổn định cho các tác vụ ngắn, khi quy trình lập luận hiển thị không gây phiền nhiễu. Mô hình có thể được thay đổi trong trình chọn giao diện hoặc bằng dòng model trong khối agent-default-model.

Thành phần mạng được quyết định bởi sự bình chọn của các thành viên và thay đổi theo thời gian; danh sách cập nhật cùng với các giới hạn luôn được cung cấp bởi GET https://gate.joingonka.ai/v1/models — đây cũng là lệnh được sử dụng bởi nút Fetch available models.

Các công cụ đại lý tiêu thụ token khác với trò chuyện: với mỗi câu lệnh của bạn, harness sẽ thêm một lời nhắc hệ thống và mô tả của tất cả các công cụ, sau đó thực hiện đối thoại nhiều bước với mô hình. Trong lượt chạy thử của chúng tôi, tác vụ «đọc tệp và tìm lỗi» mất từ hai đến ba bước và tiêu tốn từ 14 đến 22 nghìn token, trong đó hầu hết là dữ liệu đầu vào: khoảng bảy nghìn token bị tiêu thụ với mỗi bước ngay cả trước khi bạn đặt câu hỏi. Đây là chi phí bình thường cho tính tự chủ — và đó chính là lý do tại sao giá cho mỗi token lại quan trọng.

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

Thanh toán được tính theo mức tiêu thụ thực tế, không cần đăng ký và không có hạn ngạch số lượng yêu cầu; số dư và mức tiêu thụ hàng ngày có thể xem trong bảng điều khiển.

Phiên bản. Trong khi dự án đang ở trạng thái developer preview, sau mỗi lần cập nhật hãy kiểm tra xem nhà cung cấp có hoạt động không, và để đảm bảo tính tái lập, hãy cố định phiên bản ngay trong lệnh: npx @deepseek-ai/[email protected] web.

Quyền. Các phiên mới mặc định hoạt động ở chế độ Workspace Write — ghi tệp trong phạm vi thư mục làm việc; đối với các thao tác ngoài chính sách, giao diện sẽ yêu cầu xác nhận. Chế độ này có thể thay đổi trong Settings → General.

Thử lại. Khi xảy ra lỗi mạng đơn lẻ, dsh sẽ tự động thử lại yêu cầu — theo tài liệu là tối đa năm lần — vì vậy sự gia tăng tải mạng ngắn hạn thường không đáng kể.

Quyền riêng tư. Gateway không lưu trữ nội dung của lời nhắc và phản hồi: trong thống kê chỉ còn lại tổng mức tiêu thụ. Đại lý đọc các tệp dự án cục bộ trên máy của bạn.

Nếu cần làm việc với hình ảnh — ảnh chụp màn hình giao diện, sơ đồ trong ảnh — hãy thiết lập thêm một nhà cung cấp thứ hai với mô hình có khả năng xử lý thị giác: dsh giữ nhiều nhà cung cấp cùng lúc, còn các mô hình của mạng Gonka là các mô hình văn bản.

DeepSeek Harness không phải là đại lý duy nhất do phòng thí nghiệm phát triển mô hình tự sản xuất: Z.ai, tác giả của GLM, có môi trường ZCode, còn MiniMax có MiniMax Code trên terminal. Cả hai đều kết nối với cùng một gateway bằng cùng một khóa.