Bỏ qua tới nội dung
Ông T.vn

mini-swe-agent: AI agent sửa issue và chạy lệnh — hướng dẫn cài đặt và dùng

12 phút đọcCập nhật

Bài này là một góc nhìn khác về SWE-agent/mini-swe-agent — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: mini-swe-agent: agent AI 100 dòng code sửa lỗi và viết code trên terminal — hướng dẫn cài đặt và dùng →

mini-swe-agent: AI agent sửa issue và chạy lệnh — hướng dẫn cài đặt và dùng

Tóm tắt nhanh

mini-swe-agent là AI agent Python tối giản, có thể làm việc trong terminal, xử lý GitHub issue và hỗ trợ viết hoặc sửa mã qua bash. Repo phù hợp với người muốn một công cụ dễ hiểu, dễ mở rộng và chạy nhanh. Cách cài khá đơn giản bằng pip, uv hoặc pipx; README chưa mô tả chi tiết phần cấu hình model và API key.

mini-swe-agent là một AI agent tối giản chạy trong dòng lệnh, giúp bạn giao việc kỹ thuật cho mô hình ngôn ngữ thông qua bash. Agent có thể đọc mã nguồn, chạy lệnh, sửa tệp và hỗ trợ xử lý các vấn đề trong dự án phần mềm.

Điểm đáng giá nhất là repo giữ phần agent rất nhỏ và dễ đọc. Thay vì xây dựng nhiều công cụ riêng, mini-swe-agent chỉ dùng bash để tương tác với môi trường. Cách này phù hợp với dev mới, nhóm nghiên cứu AI, người cần một agent chạy nhanh hoặc người muốn tự chỉnh sửa agent theo nhu cầu.

Repo hiện có khoảng 9.586 sao và 1.313 fork. Dự án dùng Python, giấy phép MIT và vẫn còn được cập nhật. Tác giả cho biết mini-swe-agent đạt trên 74% ở SWE-bench Verified, đồng thời hỗ trợ nhiều cách triển khai môi trường như local, Docker/Podman, Singularity/Apptainer, bubblewrap và contree.

Agent

SWE-agent/mini-swe-agent

AI agent tối giản dùng dòng lệnh để xử lý GitHub issue, viết mã và thực hiện tác vụ kỹ thuật qua bash.

★ 9.6kPythonMIT
Xem repo trên GitHub

I.mini-swe-agent làm được gì

A.Làm việc trực tiếp trong terminal

Bạn có thể khởi động CLI bằng lệnh mini, sau đó giao yêu cầu bằng ngôn ngữ tự nhiên. Agent dùng bash để kiểm tra thư mục, đọc tệp, chạy chương trình và thực hiện các bước cần thiết.

Điều này hữu ích khi bạn muốn thử một agent trong dự án local mà không phải học một giao diện riêng. Với người mới, cách dùng gần với việc mô tả công việc cho một trợ lý kỹ thuật.

B.Hỗ trợ xử lý GitHub issue

Mô tả của repo tập trung vào việc giải quyết GitHub issue. Agent có thể được đặt trong thư mục dự án để phân tích mã nguồn, tìm vị trí liên quan và thực hiện các thay đổi cần thiết qua shell.

Bạn vẫn cần kiểm tra diff, chạy test và xem lại kết quả trước khi đưa mã lên repo. README không nói rằng agent tự động tạo pull request hoặc tự động hợp nhất mã.

C.Chỉ dùng bash làm công cụ

mini-swe-agent không có một bộ công cụ riêng cho từng tác vụ. Agent chỉ có bash, nên mô hình có thể tận dụng các lệnh sẵn có trong môi trường.

Thiết kế này làm phần lõi gọn hơn. Nó cũng giúp agent hoạt động với nhiều loại model, kể cả model không dùng giao diện tool-calling. Trong môi trường sandbox, bạn chỉ cần cung cấp bash và các lệnh cần thiết.

D.Lịch sử hội thoại tuyến tính

Mỗi bước của agent được nối tiếp vào chuỗi message gửi cho model. Không có cơ chế xử lý lịch sử phức tạp giữa các bước.

Với người làm nghiên cứu hoặc debug, đây là lợi thế rõ ràng. Bạn dễ theo dõi agent đã nhận yêu cầu gì, đã chạy lệnh nào và tại sao bước tiếp theo được sinh ra.

E.Chạy từng hành động độc lập

Repo thực thi hành động bằng subprocess.run. Mỗi lệnh là một lần chạy độc lập, thay vì giữ một phiên shell có trạng thái lâu dài.

Cách này giúp việc đưa agent vào sandbox đơn giản hơn. Tác giả cũng cho biết có thể thay cách gọi lệnh bằng cơ chế tương ứng như docker exec khi cần mở rộng môi trường chạy.

F.Kết nối nhiều loại model

mini-swe-agent hỗ trợ model thông qua LiteLLM, OpenRouter, Portkey và các lựa chọn khác. README cũng nói repo hỗ trợ endpoint /completion, /response và interleaved thinking.

Điểm thực tế là agent không bị khóa vào một nhà cung cấp model duy nhất. Tuy nhiên, README được cung cấp chưa ghi các bước chọn model, đặt API key hoặc cấu hình từng nhà cung cấp.

G.Có Python bindings

Ngoài CLI, repo có thể được dùng từ Python. README đưa ví dụ tạo DefaultAgent, truyền vào LitellmModel và LocalEnvironment, rồi gọi agent.run().

Đây là lựa chọn phù hợp khi bạn muốn nhúng agent vào một chương trình, thử nghiệm một workflow riêng hoặc xây dựng hệ thống đánh giá model.

H.Hỗ trợ môi trường triển khai khác nhau

README liệt kê local environment, Docker/Podman, Singularity/Apptainer, bubblewrap và contree. Các lựa chọn này phù hợp với những mức độ cô lập khác nhau.

Nếu chỉ muốn dùng thử, local environment là điểm bắt đầu đơn giản hơn. Khi agent được phép chạy lệnh trên mã nguồn quan trọng, bạn nên đọc thêm tài liệu về sandbox và quyền truy cập trước khi sử dụng.

II.Cần chuẩn bị gì

Bạn cần một môi trường có Python từ 3.10 trở lên. Thông tin này được khai báo trong pyproject.toml.

Bạn cũng cần một terminal và một thư mục dự án nếu muốn dùng agent để đọc hoặc sửa mã nguồn local. README cho biết agent làm việc qua bash, nhưng không nêu danh sách đầy đủ các lệnh hệ thống bắt buộc.

Nếu cài từ source, bạn cần Git để sao chép repo. Lệnh git clone được dùng trong hướng dẫn cài đặt của README.

README chưa ghi cụ thể hệ điều hành được hỗ trợ. Vì vậy, chưa thể kết luận chính thức rằng công cụ chạy được trên Windows, macOS hay Linux ở mọi cấu hình. README cũng chưa ghi yêu cầu GPU.

Repo hỗ trợ nhiều model qua các lớp tích hợp như LiteLLM, OpenRouter và Portkey, nhưng tư liệu được cung cấp chưa nêu API key nào cần tạo, đặt ở đâu hoặc model mặc định là gì. Bạn nên xem phần tài liệu về quick start, CLI và global configuration trong repo trước khi chạy công việc thật.

III.Cài đặt từng bước

  1. Chọn cách càiDùng uvx, pipx, pip hoặc cài từ source
  2. Cài mini-swe-agentChạy đúng lệnh tương ứng trong README
  3. Mở CLIGõ lệnh mini trong terminal
  4. Đọc tài liệu cấu hìnhKiểm tra model, môi trường và quyền chạy lệnh

A.Chọn cách cài phù hợp

README có ba lựa chọn. Nếu chỉ muốn thử CLI, dùng uvx hoặc pipx để chạy trong môi trường riêng. Nếu muốn dùng CLI và Python bindings trong môi trường hiện tại, dùng pip. Nếu muốn phát triển hoặc sửa source, clone repo rồi cài editable.

Người mới thường nên bắt đầu bằng lựa chọn thử CLI. Người muốn viết chương trình Python nên cài vào môi trường hiện tại. Người muốn đọc và chỉnh agent nên dùng cách cài từ source.

B.Cài để thử CLI

README ghi các lệnh sau:

Terminal
pip install uv && uvx mini-swe-agent
# or
pip install pipx && pipx ensurepath && pipx run mini-swe-agent

Lệnh đầu cài uv, sau đó chạy mini-swe-agent bằng uvx. Lệnh thứ hai cài pipx, cập nhật PATH bằng pipx ensurepath, rồi chạy package qua pipx.

Nếu terminal chưa nhận lệnh pipx sau pipx ensurepath, bạn có thể cần mở lại terminal. README không nêu chi tiết xử lý PATH cho từng hệ điều hành, nên hãy kiểm tra hướng dẫn của pipx nếu gặp lỗi.

C.Cài vào môi trường Python hiện tại

README ghi:

Terminal
pip install mini-swe-agent
mini  # run the CLI

Lệnh đầu cài package Python có tên mini-swe-agent. Lệnh thứ hai mở CLI bằng tên mini.

Hãy chạy các lệnh trong terminal của môi trường Python bạn muốn sử dụng. Nếu bạn đang dùng virtual environment, cần kích hoạt môi trường đó trước. README không cung cấp lệnh tạo hoặc kích hoạt virtual environment, nên không nên tự đoán thêm tên thư mục hay câu lệnh cụ thể.

D.Cài từ source để phát triển

README ghi:

Terminal
git clone https://github.com/SWE-agent/mini-swe-agent.git
cd mini-swe-agent && pip install -e .
mini  # run the CLI

git clone tải source về máy. cd mini-swe-agent chuyển terminal vào thư mục dự án. pip install -e . cài package ở chế độ editable, phù hợp khi bạn muốn sửa source và thử ngay thay đổi đó. Cuối cùng, mini mở CLI.

Bạn cần mở terminal tại thư mục mà mình muốn lưu repo. Sau khi clone, hãy kiểm tra terminal thực sự đang ở trong thư mục mini-swe-agent trước khi chạy lệnh cài đặt.

E.Đọc phần cấu hình trước khi giao việc

README dẫn tới các phần Quick start guide, Using the mini CLI, Global configuration, Yaml configuration files, cookbook và FAQ. Đây là nơi nên xem tiếp để biết cách chọn model, cấu hình CLI, dùng YAML và thiết lập môi trường an toàn.

Tư liệu được cung cấp chưa có lệnh cấu hình API key hoặc ví dụ CLI hoàn chỉnh sau khi cài. Vì vậy, chỉ cài xong chưa đồng nghĩa agent đã sẵn sàng gọi model. Đừng đưa key vào câu lệnh hoặc tệp chia sẻ công khai nếu tài liệu yêu cầu cấu hình riêng.

Agent có thể chạy bash và thay đổi tệp trong môi trường được cấp quyền. Hãy thử trên bản sao dự án, kiểm tra diff và giới hạn quyền truy cập trước khi giao việc có thể làm mất dữ liệu hoặc phát sinh chi phí model.

IV.Kiểm tra đã chạy được chưa

Sau khi cài, chạy:

Terminal
mini

Đây là lệnh README dùng để mở CLI. Nếu terminal nhận lệnh và CLI khởi động, phần cài đặt package đã hoạt động.

README không cung cấp ảnh màn hình, thông báo thành công cụ thể hoặc một prompt kiểm thử chính thức. Vì vậy, không nên tự xem một dòng chào mừng cụ thể là kết quả bắt buộc.

Bạn có thể kiểm tra thêm theo quy trình an toàn: mở CLI trong một thư mục thử nghiệm, giao một yêu cầu nhỏ chỉ đọc tệp hoặc liệt kê cấu trúc dự án, rồi xem agent có thể thực hiện bước bash tương ứng hay không. Sau đó kiểm tra lại file và terminal bằng tay.

Nếu muốn kiểm tra Python bindings, README đưa ví dụ sau:

Python
agent = DefaultAgent(
    LitellmModel(model_name=...),
    LocalEnvironment(),
)
agent.run("Write a sudoku game")

Ví dụ này cho thấy API Python gồm DefaultAgent, LitellmModel, LocalEnvironment và phương thức run. Tuy nhiên, giá trị model_name=... trong README là phần giữ chỗ, không phải tên model có thể sao chép nguyên trạng.

V.Dùng vào việc thật

A.Dev xử lý một lỗi trong repo

Một dev có thể mở terminal trong bản sao dự án, chạy mini, rồi yêu cầu agent tìm nguyên nhân của một lỗi, đọc các tệp liên quan và đề xuất thay đổi. Sau khi agent chạy xong, dev xem diff, chạy test của dự án và tự quyết định có chấp nhận thay đổi hay không.

Cách này tận dụng đúng khả năng cốt lõi của repo: agent dùng bash để đọc mã, chạy lệnh và sửa tệp. README không cung cấp một lệnh riêng cho GitHub issue, nên phần mô tả issue cần được đưa vào yêu cầu trong CLI hoặc xử lý theo hướng dẫn đầy đủ trong tài liệu.

B.Nhóm nghiên cứu đánh giá nhiều model

Nhóm nghiên cứu có thể dùng Python bindings để tạo agent với DefaultAgent, LitellmModel và LocalEnvironment. Sau đó, nhóm truyền các nhiệm vụ giống nhau cho những model khác nhau và lưu lại trajectory để phân tích.

Lịch sử tuyến tính giúp việc xem lại prompt, hành động và phản hồi dễ hơn. Đây là điểm phù hợp cho fine-tuning, reinforcement learning hoặc benchmark, nơi nhóm cần hiểu chính xác agent đã làm gì.

C.Người xây công cụ nội bộ cho đội kỹ thuật

Một nhóm có thể dùng mini-swe-agent làm lớp agent nền cho công cụ nội bộ. Ví dụ, công cụ nhận yêu cầu sửa một bài kiểm thử hoặc giải thích cấu trúc một thư mục, rồi giao nhiệm vụ cho agent chạy trong local environment.

Vì phần agent nhỏ và không phụ thuộc vào nhiều tool riêng, dev có thể đọc source nhanh và thay đổi cách chạy môi trường. Nếu cần cô lập hơn, README liệt kê Docker/Podman, Singularity/Apptainer, bubblewrap và contree là các hướng triển khai được hỗ trợ.

D.Người mới muốn thử AI agent bằng bài toán nhỏ

Bạn có thể bắt đầu bằng một thư mục thử nghiệm và giao một yêu cầu ngắn như viết một trò Sudoku, đúng với ví dụ Python trong README: agent.run("Write a sudoku game").

Sau đó, đọc các tệp được tạo, chạy thử chương trình và xem agent đã dùng những lệnh nào. Bài tập nhỏ này giúp bạn hiểu mô hình, bash, môi trường local và lịch sử tuyến tính trước khi đưa agent vào repo thật.

Một agent tốt không cần thật nhiều công cụ; đôi khi bash, lịch sử rõ ràng và một môi trường an toàn là đủ.

Ông T

VI.Lỗi hay gặp và cách xử lý

A.Terminal không nhận lệnh mini

Có thể package chưa được cài trong môi trường Python hiện tại, hoặc PATH chưa nhận chương trình sau khi dùng pipx. Hãy kiểm tra bạn đã chạy đúng một trong các lệnh cài đặt của README và đang mở đúng terminal hoặc môi trường Python.

Nếu vừa chạy pipx ensurepath, hãy mở lại terminal. README không cung cấp cách sửa PATH riêng cho từng hệ điều hành, nên cần xem tài liệu của công cụ cài đặt nếu lỗi vẫn còn.

B.Python không đủ phiên bản

pyproject.toml yêu cầu Python >=3.10. Nếu pip báo không thỏa điều kiện phiên bản, hãy dùng một Python phù hợp rồi chạy lại lệnh cài đặt trong môi trường đó.

Không nên tự sửa yêu cầu phiên bản trong pyproject.toml chỉ để ép cài, vì có thể làm phát sinh lỗi chưa được tài liệu mô tả.

C.CLI mở được nhưng chưa chạy được model

README cho biết repo hỗ trợ LiteLLM, OpenRouter, Portkey và nhiều model, nhưng phần tư liệu này chưa ghi model mặc định hoặc cách đặt API key. Hãy đọc Quick start, Using the mini CLI và Global configuration trước khi thử lại.

Không nên đoán tên biến môi trường hoặc dán key vào source. Nếu chưa tìm thấy hướng dẫn, hãy xem các tệp cấu hình và tài liệu có sẵn trong repo.

D.Agent sửa nhầm tệp hoặc chạy lệnh ngoài dự kiến

Đây là rủi ro tự nhiên của một agent có quyền dùng bash. Hãy chạy trong bản sao dự án, kiểm tra trạng thái Git và diff sau mỗi nhiệm vụ. Với dữ liệu quan trọng, dùng môi trường cô lập được README liệt kê và chỉ cấp quyền cần thiết.

E.Cài từ source nhưng thay đổi chưa có hiệu lực

Khi cài từ source, README dùng pip install -e .. Hãy bảo đảm bạn đã chạy lệnh này bên trong thư mục mini-swe-agent, không phải thư mục cha hoặc một thư mục khác.

Nếu vẫn có vấn đề, kiểm tra terminal đang dùng đúng môi trường Python và đọc thêm tài liệu đóng góp trong repo.

VII.Có nên dùng không

Bạn nên cân nhắc mini-swe-agent nếu muốn một CLI AI agent nhanh, ít cấu hình, dễ đọc và có thể dùng local. Repo cũng phù hợp với người nghiên cứu agent, vì lịch sử tuyến tính và phần lõi nhỏ giúp theo dõi, debug và thử nghiệm dễ hơn.

Điểm mạnh gồm thiết kế tối giản, chỉ dùng bash, hỗ trợ Python bindings, có nhiều lựa chọn model qua các lớp tích hợp, hỗ trợ nhiều môi trường triển khai và có hiệu năng tốt theo số liệu SWE-bench mà tác giả công bố. Giấy phép MIT cũng thuận lợi cho việc dùng và chỉnh sửa theo dự án.

Giới hạn là README được cung cấp chưa giải thích đầy đủ cách cấu hình model, API key, hệ điều hành, GPU hoặc quy trình xử lý GitHub issue từ đầu đến cuối. Agent dùng bash nên hiệu quả và độ an toàn phụ thuộc nhiều vào model, thư mục làm việc và quyền bạn cấp.

Nếu bạn cần một hệ thống có nhiều tool chuyên biệt, giao diện phức tạp hoặc cơ chế xử lý lịch sử tùy biến sâu, README khuyên cân nhắc SWE-agent. Ngược lại, nếu mục tiêu là một agent dòng lệnh đơn giản, dễ hack và dễ triển khai, mini-swe-agent là lựa chọn đáng thử.

Khi bắt đầu, hãy dùng một thư mục thử nghiệm, cài theo đúng một trong ba cách của README, chạy mini, rồi đọc tài liệu cấu hình trước khi kết nối model hoặc giao tác vụ có thể thay đổi dữ liệu thật.

3.9/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn không?

Câu hỏi thường gặp

mini-swe-agent có miễn phí không?

Repo dùng giấy phép MIT. README không nêu chi phí sử dụng model hoặc các dịch vụ tích hợp, nên chi phí thực tế của việc gọi model chưa được xác định từ tư liệu này.

Có cần GPU để chạy mini-swe-agent không?

README không nêu yêu cầu GPU. Repo hỗ trợ nhiều model qua LiteLLM, OpenRouter, Portkey và các lựa chọn khác, nhưng chưa ghi chi tiết phần cứng cho từng model.

mini-swe-agent chạy được trên Windows không?

Tư liệu được cung cấp chưa nêu hệ điều hành được hỗ trợ. Vì agent làm việc qua bash, bạn nên kiểm tra tài liệu và môi trường cụ thể trước khi triển khai trên Windows.

Có cần API key không?

README nói repo hỗ trợ nhiều model và các lớp tích hợp, nhưng phần được cung cấp chưa ghi API key nào cần dùng, đặt ở đâu hoặc cấu hình thế nào. Hãy xem tài liệu Quick start và Global configuration trong repo.

mini-swe-agent khác SWE-agent ở điểm nào?

mini-swe-agent đơn giản hơn, chỉ dùng bash, có lịch sử tuyến tính và thực thi hành động độc lập bằng `subprocess.run`. README gợi ý dùng SWE-agent khi bạn muốn thử nhiều bộ tool hoặc các cách xử lý lịch sử khác nhau.

Agent có tự tạo pull request không?

README nói agent có thể giúp xử lý GitHub issue, nhưng không cam kết quy trình tự động tạo hoặc hợp nhất pull request. Tác giả chỉ nêu rằng bạn có thể yêu cầu model tự tìm cách thực hiện các việc như mở PR.

Dữ liệu và mã nguồn có an toàn không?

README liệt kê nhiều môi trường triển khai gồm local, Docker/Podman, Singularity/Apptainer, bubblewrap và contree. Tuy vậy, tư liệu chưa đưa chính sách dữ liệu hoặc cấu hình an toàn đầy đủ; bạn nên giới hạn quyền và thử trên bản sao dự án.

Chuyển nhanh tới mục

  1. I.mini-swe-agent làm được gì
    1. A.Làm việc trực tiếp trong terminal
    2. B.Hỗ trợ xử lý GitHub issue
    3. C.Chỉ dùng bash làm công cụ
    4. D.Lịch sử hội thoại tuyến tính
    5. E.Chạy từng hành động độc lập
    6. F.Kết nối nhiều loại model
    7. G.Có Python bindings
    8. H.Hỗ trợ môi trường triển khai khác nhau
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Chọn cách cài phù hợp
    2. B.Cài để thử CLI
    3. C.Cài vào môi trường Python hiện tại
    4. D.Cài từ source để phát triển
    5. E.Đọc phần cấu hình trước khi giao việc
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Dev xử lý một lỗi trong repo
    2. B.Nhóm nghiên cứu đánh giá nhiều model
    3. C.Người xây công cụ nội bộ cho đội kỹ thuật
    4. D.Người mới muốn thử AI agent bằng bài toán nhỏ
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Terminal không nhận lệnh mini
    2. B.Python không đủ phiên bản
    3. C.CLI mở được nhưng chưa chạy được model
    4. D.Agent sửa nhầm tệp hoặc chạy lệnh ngoài dự kiến
    5. E.Cài từ source nhưng thay đổi chưa có hiệu lực
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.