# mini-swe-agent: agent AI 100 dòng code sửa lỗi và làm việc trong terminal — hướng dẫn cài đặt và dùng

> mini-swe-agent là một agent AI lập trình rất gọn, viết bằng Python. Phần lõi chỉ khoảng 100 dòng, và agent chỉ dùng bash để làm việc. Bạn gõ lệnh `mini` trong terminal rồi giao việc cho nó, như sửa lỗi hay viết một chương trình nhỏ. Cài bằng pip chỉ một lệnh, nhưng bạn cần có sẵn tài khoản mô hình AI để nó chạy.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-24 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/mini-swe-agent-agent-ai-100-dong-code-huong-dan-cai-dat-2

mini-swe-agent là một agent AI viết code chạy ngay trong terminal. Phần lõi của nó chỉ khoảng 100 dòng Python. Nó không có bộ công cụ cầu kỳ nào, chỉ dùng bash để đọc file, sửa file, chạy test và làm những việc còn lại. Bạn giao việc bằng ngôn ngữ thường, nó tự nghĩ từng bước và gõ lệnh.

Repo này dành cho ba nhóm người. Nhóm thứ nhất là lập trình viên muốn một công cụ dòng lệnh nhẹ, khởi động nhanh, đọc code là hiểu. Nhóm thứ hai là người mới muốn thấy tận mắt một agent AI hoạt động thế nào bên trong. Nhóm thứ ba là người làm nghiên cứu hoặc đánh giá mô hình, cần một nền (baseline) đơn giản để so sánh các mô hình ngôn ngữ với nhau.

Điều đáng giá nhất là sự đơn giản mà vẫn mạnh. Theo tác giả, dù gọn như vậy, agent vẫn đạt hơn 74% trên bộ đo SWE-bench verified. Đây là bài đo để xem AI sửa lỗi phần mềm thật tốt đến đâu. Repo do nhóm ở Princeton và Stanford làm, chính là nhóm đứng sau SWE-bench và SWE-agent. Hiện có khoảng 9573 sao và 1307 fork trên GitHub, giấy phép MIT.

```repo
- repo | SWE-agent/mini-swe-agent
- kind | Agent
- desc | mini-swe-agent là agent AI viết code chỉ khoảng 100 dòng Python, chỉ dùng bash, chạy ngay trong terminal và đạt hơn 74% trên SWE-bench verified.
- stars | 9.6k
- lang | Python
- license | MIT
```

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

Dưới đây là những điểm chính, giải thích theo lợi ích bạn nhận được.

**Chỉ dùng bash, không cần công cụ riêng.** Agent không có công cụ nào khác ngoài bash. Nó thậm chí không cần dùng giao diện gọi công cụ (tool-calling) của mô hình AI. Nhờ vậy gần như mô hình nào cũng chạy được. Muốn nó làm việc gì đó, như mở pull request, bạn chỉ cần bảo nó tự tìm cách, không cần chờ ai viết thêm tính năng.

**Lịch sử tuyến tính.** Mỗi bước chạy chỉ nối thêm vào danh sách tin nhắn, và hết. Cái bạn thấy trong lịch sử chính là cái được gửi cho mô hình ở bước sau. Khi agent làm sai, bạn dễ đọc lại để biết nó đã bị nhắc cái gì.

**Mỗi lệnh chạy độc lập.** Agent chạy lệnh bằng `subprocess.run`, không giữ một phiên shell mở liên tục. Tác giả nói việc này giúp agent ổn định hơn. Muốn chạy trong môi trường cô lập, về nguyên tắc chỉ cần thay `subprocess.run` bằng `docker exec`.

**Nhiều môi trường chạy.** README liệt kê môi trường local, docker/podman, singularity/apptainer, bubblewrap, contree và nhiều loại khác. Bạn có thể bắt đầu ngay trên máy mình, sau đó chuyển sang môi trường cô lập khi cần an toàn hơn.

**Nhiều loại mô hình.** Agent hỗ trợ mọi mô hình qua litellm, openrouter, portkey và các nguồn khác. README cũng nói có hỗ trợ endpoint `/completion` và `/response`, cùng interleaved thinking.

**Có cả dòng lệnh, chạy hàng loạt, trình duyệt lịch sử và Python.** README nêu bốn cách dùng: CLI (`mini`), batch inference, trình duyệt lịch sử chạy (trajectory browser), và gọi từ Python. Với người mới, CLI là cách dễ nhất.

README còn nói agent khởi động nhanh hơn Claude Code. Repo cũng có sẵn hướng dẫn riêng cho AI trong các file `AGENTS.md` và `CLAUDE.md`.

## Cần chuẩn bị gì

Tư liệu chỉ nêu rõ vài thứ:

- **Python 3.10 trở lên.** Đây là yêu cầu trong file `pyproject.toml` của repo.
- **pip.** Các lệnh cài đặt trong README đều dùng pip (hoặc uv, pipx).
- **Một mô hình AI để agent gọi.** Agent không tự có "bộ não". README nói nó hỗ trợ mô hình qua litellm, openrouter, portkey và các nguồn khác, nên bạn cần một nguồn mô hình trong số đó.

Về API key, biến môi trường hay chỗ khai báo mô hình, phần README mình có không ghi chi tiết. Phần đó nằm ở tài liệu của dự án (mục Quick start và Global configuration). Mình sẽ không đoán tên biến cho bạn, vì đoán sai sẽ mất công hơn.

README cũng không nói về hệ điều hành hay phần cứng bắt buộc. Dự án có chạy được trên Windows hay không thì tư liệu chưa nói rõ.

```note
Agent tự gõ lệnh bash trên máy bạn. Lần đầu hãy thử trong một thư mục trống hoặc thư mục dự án thử nghiệm, đừng chạy trong thư mục chứa dữ liệu quan trọng. Gọi mô hình AI qua API thường tính phí theo lượng dùng, nên bạn hãy theo dõi chi phí ở nơi cung cấp mô hình.
```

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

README đưa ra ba cách cài. Mình tóm tắt trước, rồi đi từng bước.

```steps
- Kiểm tra Python | Chắc chắn máy có Python 3.10 trở lên và pip
- Chọn cách cài | Chạy thử không cài (uvx/pipx), cài vào máy bằng pip, hoặc cài từ mã nguồn
- Chạy lệnh cài | Dán đúng lệnh của cách bạn chọn vào terminal
- Gõ mini | Mở giao diện dòng lệnh của agent
- Cấu hình mô hình | Làm theo mục Quick start trong tài liệu của dự án
```

### Mở terminal và kiểm tra Python

Trên Windows, bạn mở PowerShell hoặc Terminal. Trên macOS và Linux, bạn mở Terminal. Hãy chắc là máy có Python từ 3.10 trở lên. Kiểm tra phiên bản bằng lệnh phổ thông:

```bash
python --version
```

Nếu máy báo không tìm thấy lệnh này, trên một số máy bạn thử `python3 --version`. Nếu phiên bản thấp hơn 3.10, bạn cần cài bản Python mới hơn trước.

### Cách 1: chạy thử, không cài vào máy

Cách này hợp nếu bạn chỉ muốn xem thử. Gói được cài vào một môi trường ảo tạm thời, không làm bừa máy của bạn. README ghi hai biến thể, bạn chọn một:

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

Dòng đầu cài `uv` rồi chạy gói `mini-swe-agent` bằng `uvx`. Dòng cuối (sau chữ `or`) cài `pipx`, rồi chạy gói bằng `pipx run`. Bạn chỉ cần chạy một trong hai, không chạy cả hai. Chữ `# or` là chú thích, không phải lệnh.

Chỗ người mới hay vấp là `pipx ensurepath`. Lệnh này sửa biến PATH. Sau khi chạy, bạn nên đóng terminal rồi mở lại.

### Cách 2: cài vào môi trường hiện tại

Cách này cài cả dòng lệnh lẫn thư viện Python để bạn gọi trong code. Nó hợp nếu bạn định dùng agent thường xuyên:

```bash
pip install mini-swe-agent
mini  # run the CLI
```

Lệnh đầu cài gói. Lệnh `mini` mở giao diện dòng lệnh của agent. Phần sau dấu `#` là chú thích. Nếu bạn đang dùng một môi trường ảo Python, hãy kích hoạt nó trước khi cài, để agent không lẫn với các gói khác trên máy.

### Cách 3: cài từ mã nguồn

Cách này dành cho người muốn đọc hoặc sửa code của agent:

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

Lệnh `git clone` tải mã nguồn về máy. Lệnh `cd` đi vào thư mục vừa tải. Lệnh `pip install -e .` cài ở chế độ chỉnh sửa được, nghĩa là bạn sửa code trong thư mục thì agent dùng ngay bản sửa. Máy cần có Git. Nhớ chạy `pip install -e .` khi đang đứng trong thư mục `mini-swe-agent`, nếu không lệnh sẽ báo lỗi.

### Cấu hình mô hình AI

Phần README mình có chỉ nói đến việc gõ `mini` để chạy. README chưa ghi cách điền key hay chọn mô hình. Bạn xem mục Quick start và Global configuration trong tài liệu của dự án (trang chủ mini-swe-agent.com). Trong repo có thư mục `docs/` chứa nội dung tài liệu đó.

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

Cách kiểm tra đơn giản nhất là gõ lệnh sau trong terminal, ở nơi bạn đã cài:

```bash
mini
```

Nếu cài thành công, lệnh này mở giao diện dòng lệnh của agent. Hướng dẫn trong README là cứ gõ `mini` để chạy CLI. Nếu terminal báo không tìm thấy lệnh `mini`, gói chưa cài xong hoặc terminal chưa nhận PATH mới. Bạn đóng terminal, mở lại rồi thử lần nữa.

Nếu giao diện mở ra nhưng agent không trả lời được, nhiều khả năng mô hình AI chưa được cấu hình. Lúc đó hãy quay lại mục Quick start trong tài liệu. README chưa mô tả màn hình hay thông báo cụ thể khi thành công, nên mình không nêu ra những gì chưa có trong tư liệu.

Nếu bạn muốn thử từ Python, README có một đoạn ví dụ. Nó chỉ cho thấy cách ghép các phần lại với nhau. Chỗ `...` là tên mô hình bạn tự điền, đoạn này không chạy được nếu để nguyên:

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

Đoạn mã trên tạo một agent mặc định, gắn với một mô hình qua litellm và một môi trường chạy trên máy bạn, rồi giao việc "Write a sudoku game" (viết trò sudoku). Các lệnh `import` cần thiết README không in ra ở phần này, nên bạn xem thêm trong tài liệu nếu muốn chạy thật.

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

Dưới đây là vài tình huống bám đúng khả năng repo. Agent hoạt động bằng cách bạn mô tả việc, nó tự gõ lệnh bash để làm. Các câu lệnh mẫu bên dưới là câu bạn nhập cho agent, không phải cờ lệnh của `mini`.

### Dev mới nhờ agent viết một chương trình nhỏ

Bối cảnh: bạn mới học lập trình, muốn xem một chương trình hoàn chỉnh trông thế nào. Bạn mở terminal trong một thư mục trống, gõ `mini`, rồi nhập yêu cầu. README dùng chính ví dụ này:

```text
Write a sudoku game
```

Agent sẽ tự chạy các lệnh trong shell để tạo file và kiểm tra. Kết quả là một chương trình nằm ngay trong thư mục của bạn. Bạn mở file ra đọc, hỏi lại agent chỗ nào chưa hiểu. Đây là cách học khá nhanh vì mọi bước đều nằm trong lịch sử tuyến tính, dễ lần lại.

> Agent không cần mười công cụ. Nó cần một cái shell và một mô hình đủ giỏi.
>
> — Ông T

### Lập trình viên sửa lỗi trong dự án có sẵn

Bối cảnh: bạn có một dự án Python đang lỗi test. Bạn mở terminal trong thư mục dự án, gõ `mini`, rồi mô tả lỗi bằng lời. Ví dụ:

```text
Các test trong thư mục tests đang lỗi. Hãy tìm nguyên nhân và sửa code, sau đó chạy lại test để xác nhận.
```

Đây đúng là hướng repo được thiết kế: giải các issue phần mềm. Agent sẽ đọc code, sửa và chạy lại lệnh để kiểm tra. Bạn nên kiểm tra kỹ phần nó đã sửa trước khi giữ lại thay đổi. Nếu dự án có Git, bạn xem `git diff` để thấy từng thay đổi.

### Nhờ agent làm việc lặt vặt trên dòng lệnh

Bối cảnh: bạn làm văn phòng hoặc kinh doanh, có một thư mục đầy file CSV xuất từ phần mềm bán hàng và muốn gộp lại. Bạn mở terminal trong thư mục đó, gõ `mini` và nhập yêu cầu:

```text
Trong thư mục này có nhiều file CSV cùng cấu trúc. Hãy gộp chúng thành một file duy nhất tên gop.csv, không sửa các file gốc.
```

README nói công cụ này giúp bạn "trong dòng lệnh", và agent chỉ có bash. Nghĩa là nó làm được những việc mà shell và Python trên máy làm được. Bạn nhớ dặn rõ "không sửa file gốc" như ví dụ trên để tránh mất dữ liệu.

### Người nghiên cứu so sánh mô hình AI

Bối cảnh: bạn muốn xem mô hình AI nào làm việc lập trình tốt hơn. Vì agent đơn giản và không phụ thuộc công cụ riêng, README nói nó rất hợp làm hệ thống nền để đo mô hình ngôn ngữ. Repo có chế độ chạy hàng loạt và trình duyệt lịch sử chạy để xem lại kết quả. Cách chạy chi tiết hai phần này nằm trong tài liệu của dự án, README chưa ghi lệnh cụ thể nên mình không liệt kê ở đây.

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

**Terminal báo không tìm thấy lệnh `mini`.** Thường là gói chưa cài, hoặc cài vào một môi trường ảo bạn chưa kích hoạt, hoặc PATH chưa cập nhật. Hãy mở terminal mới, kích hoạt đúng môi trường, rồi thử lại. Nếu dùng pipx, nhớ chạy `pipx ensurepath` và mở lại terminal.

**Lỗi phiên bản Python.** Repo yêu cầu Python 3.10 trở lên. Nếu máy bạn dùng bản thấp hơn, pip có thể báo gói không tương thích. Hãy cài bản Python mới hơn rồi cài lại.

**Agent chạy nhưng không gọi được mô hình.** Thường là chưa cấu hình mô hình hoặc API key. Mình không đoán tên biến môi trường ở đây. Bạn xem mục Quick start và Global configuration trong tài liệu dự án. Khi điền key, đừng dán key vào chỗ công khai như tin nhắn nhóm hay repo Git.

**Agent làm sai hoặc đi lòng vòng.** Đây là chuyện thường với mọi agent AI. Hãy chia việc nhỏ hơn, mô tả rõ yêu cầu và nơi cần sửa. Vì lịch sử là tuyến tính, bạn có thể đọc lại từng bước để thấy nó hiểu sai ở đâu.

**Agent chạy lệnh mà bạn không mong muốn.** Vì nó gõ lệnh bash thật trên máy, hãy thử trong thư mục thử nghiệm hoặc sao lưu trước. Nếu cần an toàn hơn, README nói repo hỗ trợ chạy trong docker/podman và các môi trường cô lập khác. Cách thiết lập chi tiết bạn xem trong tài liệu.

## Có nên dùng không

**Điểm mạnh.** Repo rất gọn nên dễ đọc, dễ sửa và dễ hiểu. Cài chỉ cần pip. Nó hỗ trợ nhiều mô hình và nhiều môi trường chạy, từ máy bạn đến docker. Tác giả nói nó đạt hơn 74% trên SWE-bench verified và khởi động nhanh hơn Claude Code. Repo vẫn được cập nhật trong 3 tháng gần đây, giấy phép MIT dùng khá thoải mái.

**Giới hạn.** Đây là công cụ dòng lệnh, không có giao diện đồ hoạ kiểu ứng dụng. Nếu bạn chưa quen mở terminal, bước đầu sẽ hơi lạ. Agent không tự có mô hình AI, bạn phải có nguồn mô hình riêng, và có thể mất phí khi gọi. README phần mình có chưa nói gì về Windows, cũng chưa nói rõ cách cấu hình mô hình, nên bạn cần đọc thêm tài liệu của dự án. Ngoài ra đây là phiên bản v2, README cảnh báo có hướng dẫn chuyển từ v1 sang. Nếu bạn từng dùng bản cũ, hãy đọc hướng dẫn đó trước.

**Khi nào chọn cách khác.** README đề xuất dùng mini-swe-agent làm lựa chọn mặc định. Nếu bạn muốn thử nghiệm nhiều bộ công cụ riêng, mỗi cái một giao diện, hoặc thử nhiều cách xử lý lịch sử, tác giả khuyên dùng SWE-agent, repo đàn anh cùng nhóm. Nếu bạn cần một ứng dụng có giao diện bấm chuột đầy đủ, công cụ này không phải loại đó.

Nói gọn: nếu bạn thoải mái với terminal và muốn một agent nhỏ, rõ ràng, dễ kiểm soát, mini-swe-agent đáng để thử. Hãy bắt đầu với cách 1 hoặc 2, trong một thư mục thử nghiệm.

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

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

Bản thân repo dùng giấy phép MIT và cài bằng pip. Tuy vậy, agent cần gọi một mô hình AI, và README không nói về chi phí của phần này. Nếu bạn dùng mô hình qua API có tính phí, bạn sẽ trả phí cho nhà cung cấp đó.

### mini-swe-agent có cần GPU không?

Tư liệu không nêu yêu cầu GPU hay phần cứng riêng nào. Agent gọi mô hình qua các nguồn như litellm hoặc openrouter, nên phần nặng nhất do mô hình đảm nhiệm. Nếu bạn dùng mô hình chạy trên máy mình thì yêu cầu phần cứng phụ thuộc vào mô hình đó, tư liệu chưa có thông tin.

### Chạy được trên Windows không?

README không nói rõ về hệ điều hành. Gói là Python (cần Python 3.10 trở lên) và cài bằng pip, nhưng tư liệu chưa khẳng định Windows chạy tốt thế nào. Bạn nên thử trước trong một thư mục thử nghiệm và xem tài liệu của dự án.

### Dữ liệu và máy của tôi có an toàn không?

Agent chạy lệnh bash thật, nên nó có thể thay đổi file trên máy bạn nếu chạy ở môi trường local. README nói repo hỗ trợ các môi trường cô lập như docker/podman, singularity/apptainer, bubblewrap. Nếu lo ngại, hãy thử trong thư mục thử nghiệm hoặc dùng môi trường cô lập. Chi tiết về dữ liệu gửi cho mô hình tuỳ nguồn mô hình bạn chọn, tư liệu chưa nói rõ.

### mini-swe-agent khác SWE-agent thế nào?

README nói mini-swe-agent là lựa chọn mặc định, đơn giản hơn nhiều: chỉ dùng bash, lịch sử tuyến tính, mỗi lệnh chạy độc lập. SWE-agent hợp hơn nếu bạn muốn thử nhiều bộ công cụ có giao diện riêng hoặc nhiều cách xử lý lịch sử.

### Tôi cần dùng mô hình AI nào?

README nói agent hỗ trợ mọi mô hình qua litellm, openrouter, portkey và các nguồn khác, vì nó chỉ dùng bash chứ không cần giao diện gọi công cụ của mô hình. Tư liệu mình có không khuyến nghị một mô hình cụ thể. Cách chọn và cấu hình nằm trong tài liệu của dự án.

### Tôi có thể gọi mini-swe-agent từ code Python không?

Có. README có ví dụ tạo DefaultAgent với LitellmModel và LocalEnvironment rồi gọi agent.run với một yêu cầu bằng chữ. Cài bằng pip install mini-swe-agent là có cả dòng lệnh lẫn thư viện Python.
