---
title: "Agent harness là gì? Hướng dẫn cho người mới"
description: "Agent vẫn làm sai dù đã có file hướng dẫn? Tìm hiểu harness trong Codex và Claude Code, cách kiểm thông tin agent đọc, đặt lời dặn cụ thể, dùng quyền chặn và xác định lúc cần nhờ lập trình viên."
canonical: "https://200lab.io/blog/agent-harness-la-gi"
published: "2026-09-26T02:55:45Z"
updated: "2026-09-26T02:55:45Z"
authors: ["Hướng nội"]
tags: ["AI", "Agent"]
reading_minutes: 15
access: "public"
---

Giả sử cuối tháng bạn nhờ agent đọc file doanh thu và viết một bản báo cáo ngắn. Trong file hướng dẫn của dự án, bạn đã dặn 2 điều: chỉ dùng số trong file đó, không sửa file gốc. Vậy mà bản báo cáo lại có câu "doanh thu tháng này tăng mạnh so với tháng trước", dù file không hề có số của tháng trước, còn file gốc thì bị agent thêm vào một cột tính tổng.Nếu bạn dùng Codex hoặc Claude Code hằng ngày thì 2 lỗi này là lý do bạn nên biết agent harness là gì?.

Từ câu bạn gõ đến bản báo cáo bạn nhận được, có 2 thứ cùng tham gia.

- 1\. **Mô hình AI:** chỉ đọc và viết ra văn bản, tự nó không mở được file nào trên máy của bạn.
- 2\. **Harness**: tức lớp phần mềm bao bên ngoài mô hình. Harness mở file doanh thu ra cho mô hình đọc, gửi kèm lời dặn của bạn, và quyết định agent có được sửa file nào trên máy hay không.

Với mô hình thì lời dặn của bạn chỉ là một đoạn chữ để nó đọc, chứ không phải một luật chặn. Vì vậy mô hình vẫn có thể viết ra câu so sánh với tháng trước, và nếu bạn chưa đặt bước kiểm nào thì harness cũng để câu đó đi qua. Còn muốn agent không sửa file gốc, bạn phải đặt một luật trong phần cấp quyền của công cụ, tức nơi bạn cho phép hay cấm agent làm từng việc.

Hiểu được chuyện này thì lần sau gặp lỗi, bạn sẽ biết cần kiểm tra chỗ nào thay vì ngồi viết lại lời dặn dài hơn. Bạn xem harness có thật sự đưa file hướng dẫn cho mô hình đọc hay không, và lời dặn đã đủ cụ thể chưa. Bạn cũng xem việc nào phải chặn hẳn bằng quyền chứ không chỉ dặn bằng lời, và ai sẽ đối chiếu bản báo cáo với file doanh thu trước khi gửi đi.

## 1. Agent harness là gì?

Quay lại bản báo cáo doanh thu: mô hình AI (phần đọc thông tin rồi chọn bước tiếp theo) không tự mở được file doanh thu trên máy của bạn. Việc mở file là do harness làm: nó gọi công cụ đọc file, rồi đưa nội dung về cho mô hình. Mô hình đọc xong thì quyết định làm gì tiếp, và agent cứ thế đi vòng vòng: đọc file, viết một đoạn báo cáo, rồi đọc lại xem đã đúng chưa, cho tới khi nó thấy là xong.

Anthropic giải thích rằng Claude Code chính là một harness. Codex cũng chạy đúng vòng lặp như vậy, bên ngoài mô hình của nó cũng có một lớp phần mềm quản lý các công cụ và quyết định agent được làm gì. Vì thế vòng lặp đề cập đến ở trên chắc chắn bạn đang dùng rồi, ngay trong công cụ Claude/Codex, nên để hiểu về harness thì bạn không phải cài thêm ứng dụng nào khác.

LangChain giải thích ngắn gọn hơn: một agent là mô hình cộng với harness. Cách nói đó không có nghĩa là harness quan trọng hơn mô hình, vì cả hai cùng quyết định kết quả bạn nhận được. Nếu bạn đang dùng song song Claude Code và Codex như trong bài [cách phối hợp Claude, Codex và Grok CLI](https://200lab.io/blog/cach-phoi-hop-claude-codex-va-grok-cli), thì bạn cần biết đây là 2 harness khác nhau, mỗi harness đọc một file hướng dẫn riêng.

## 2. Các thành phần của agent harness trong Codex và Claude Code

Ngữ cảnh (context) là toàn bộ thông tin mô hình nhìn thấy mỗi lần nó trả lời, và chính harness chọn đưa gì vào đó. Lời dặn của bạn chỉ là một phần trong số thông tin đó, còn agent có được chạy công cụ nào hay không thì harness quyết định.

| Nhiệm vụ của harness | Vị trí cấu hình trong Codex và Claude Code | Giới hạn cần lưu ý |
| --- | --- | --- |
| Nạp chỉ dẫn vào phiên làm việc | Claude Code: file `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md` (áp dụng theo dự án) hoặc `~/.claude/CLAUDE.md` (áp dụng cho mọi dự án). Codex: file `AGENTS.md` trong dự án hoặc `~/.codex/AGENTS.md` cho mọi dự án. | Mô hình đọc lời dặn nhưng không chắc làm theo. Bạn đặt file ở đâu thì lời dặn áp dụng tới đó. |
| Quản lý ngữ cảnh (context) | Claude Code: dùng các lệnh `/context`, `/compact`, `/clear`. Codex: tự dựng lại chuỗi hướng dẫn mỗi khi khởi chạy. | Bạn trò chuyện càng dài thì lời dặn ban đầu càng dễ trôi mất. Codex còn giới hạn tổng dung lượng các file hướng dẫn ở mức 32 KiB. |
| Nạp kỹ năng bổ trợ (skill) khi cần | Claude Code: lưu tại thư mục `.claude/skills/<tên>/SKILL.md` và gọi bằng cú pháp `/tên`. | Skill vẫn chỉ là lời dặn viết thành chữ, và harness chỉ nạp nội dung đó khi bạn gọi tới. |
| Kết nối công cụ và dữ liệu ngoài qua MCP (chuẩn kết nối AI với hệ sinh thái bên ngoài) | Claude Code: dùng lệnh `claude mcp`. Codex: khai báo trong mục `[mcp_servers]` tại file `~/.codex/config.toml`. | Thêm kết nối thì agent làm được nhiều việc hơn, nhưng kết quả nó trả về không vì thế mà đúng hơn. |
| Kiểm soát quyền hạn và môi trường cách ly (sandbox) | Claude Code: dùng lệnh `/permissions` hoặc sửa file `.claude/settings.json`. Codex: dùng lệnh `/permissions` hoặc các tham số `--sandbox`, `--ask-for-approval`. | Harness thực thi phần quyền này chứ không chỉ nhắc lại. Trong Codex, `never` tắt các câu hỏi xác nhận nhưng vẫn giữ nguyên sandbox. |
| Lưu trạng thái phiên làm việc | Claude Code: lưu dữ liệu các phiên làm việc tại thư mục `~/.claude/projects/`. | Bạn không có file cấu hình nào để tự sửa trạng thái phiên bằng tay. |

Có một chỗ bạn nên biết trước: Claude Code mặc định bỏ qua `AGENTS.md` nếu nó thấy `CLAUDE.md`, `.claude/CLAUDE.md` hoặc `CLAUDE.local.md` ở thư mục bạn đang làm hay ở thư mục cha. Bạn đổi được cách đọc này trong `/config`.

Bạn dặn agent đừng sửa file doanh thu gốc là một chuyện, còn chặn công cụ sửa file đó lại là chuyện khác. Một cách để chặn là dùng hook, tức là lệnh chạy tự động vào một thời điểm cố định trong lúc agent làm việc. Nhưng hook không tự biết nó phải canh thao tác nào, bạn phải ghi rõ ra. Nếu hook chạy lâu quá thời gian chờ thì Claude Code bỏ qua nó, và thao tác vẫn đi tiếp như lúc chưa có hook.

LangChain và vài nơi khác dùng chữ harness theo nghĩa khá rộng, nhưng harness, framework và runtime không phải 3 tên gọi của cùng một thứ. Framework là bộ khung để xây ứng dụng, còn runtime là môi trường chạy ứng dụng đó. Về chuyện nối AI với dữ liệu bên ngoài, mình có một bài riêng về [MCP](https://200lab.io/blog/model-context-protocol-mcp-la-gi), viết cho bạn nào làm lập trình và muốn đi sâu hơn.

## 3. Harness engineering là gì?

Harness engineering là việc bạn chỉnh lại chính cái harness đó: nó đưa thông tin gì cho agent, và giữ agent trong giới hạn nào. Với bản báo cáo doanh thu, khi agent tự viết ra câu so sánh với tháng trước, bạn xem lại nên sửa lời dặn, bổ sung thông tin, hay đặt thêm một bước kiểm kết quả.

Mitchell Hashimoto gọi cách làm của ông là harness engineering: mỗi lần agent làm sai, ông dừng lại tìm cách để nó không lặp lại lỗi đó nữa. Đó là mục tiêu ông đặt ra cho bản thân, chứ thêm một luật không có nghĩa là agent sẽ hết hẳn lỗi đó.

Ông gợi ý 2 hướng: bạn sửa file `AGENTS.md`, hoặc bạn viết một công cụ để agent tự kiểm lại việc nó làm. Hướng thứ nhất bạn tự làm được, vì bạn viết lời dặn bằng tiếng Việt. Hướng thứ hai thì mình khuyên bạn nhờ lập trình viên, vì phải có người đọc được công cụ kiểm đó mới biết nó có bắt đúng lỗi hay không.

Trong ví dụ này, lời dặn phải nói rõ là agent chỉ được lấy số trong file doanh thu có sẵn. Dặn xong rồi bạn vẫn phải mở bản báo cáo ra và đối chiếu với file gốc. Anthropic nhắc rằng agent hay chấm điểm quá cao cho thứ chính nó vừa làm. Nếu bạn không đặt thêm bước kiểm kết quả, agent có thể dừng ngay khi nó tưởng đã làm xong.

## 4. Hướng dẫn chỉnh agent harness cho một dự án

Bạn nên thử 4 bước dưới đây trên một dự án riêng, đừng làm ngay trên thư mục quan trọng thật. Trước khi sửa, bạn chép bản gốc của file hướng dẫn ra một chỗ khác. Với bản báo cáo doanh thu, bạn tách 2 yêu cầu ra: một là chỉ dùng đúng số trong file, hai là giữ nguyên file doanh thu gốc.

**Bước 1. Xem agent đang đọc file hướng dẫn nào.**

Trong Claude Code, bạn gõ `/context` rồi nhìn mục `Memory files`, đó là danh sách các file ghi nhớ. Tài liệu ghi rằng nếu `CLAUDE.md` không có trong danh sách này thì Claude không thấy file đó. Lệnh `/memory` liệt kê các chỗ có thể đặt file hướng dẫn, kể cả chỗ chưa có file nào. Từ danh sách đó, bạn mở file ra sửa được luôn. Nhưng một file có tên trong `/memory` thì chưa có nghĩa là Claude đã nạp nó vào phiên làm việc.

Với Codex, tài liệu của OpenAI chỉ cách chạy kèm tuỳ chọn `--ask-for-approval never`, rồi yêu cầu Codex tóm tắt các lời dặn đang áp dụng:

```
codex --ask-for-approval never "Tóm tắt các hướng dẫn bạn đang áp dụng."
```

Codex đọc file hướng dẫn từ thư mục gốc của dự án đi xuống tới thư mục bạn đang làm. File nằm càng gần thư mục đang làm thì càng được ưu tiên, và có thể ghi đè lời dặn của file ở tầng trên. Agent có thể nhắc lại đúng luật mà khi làm việc vẫn không làm theo, nên bản tóm tắt đó chỉ cho bạn biết nó đang đọc file hướng dẫn nào.

**Bước 2. Viết luật cụ thể cho đúng lỗi.**

Bạn bỏ lời dặn kiểu “viết báo cáo cho chuẩn” đi và thay bằng một câu cụ thể: “Chỉ dùng số có trong file doanh thu. Thiếu số nào thì ghi là thiếu, không tự so sánh với tháng khác.”

Bạn chỉ cần thêm một đoạn mới và đặt nó thành một mục riêng trong file. Sau này nếu không muốn giữ luật đó nữa thì bạn xoá đúng đoạn đó. Bạn cũng nên bỏ những lời dặn trùng hoặc mâu thuẫn nhau, vì khi 2 file hướng dẫn nói ngược nhau thì bạn không biết trước Claude sẽ làm theo bên nào. File càng dài thì luật quan trọng càng dễ bị bỏ qua.

**Bước 3. Chặn bằng quyền, đừng chỉ dặn bằng lời.**

Trong Claude Code, bạn gõ `/permissions` để xem và thêm luật, và danh sách hiện ra cũng cho biết từng luật đang nằm ở file cấu hình nào. Muốn chặn agent sửa một file thì bạn viết luật `deny` theo dạng `Edit(đường-dẫn)`. Nếu viết theo dạng `Write(...)` thì Claude Code không dùng tới luật đó khi xét quyền, nên nó không bảo vệ được file của bạn. Luật này chặn công cụ sửa file của Claude Code, chứ nó không chặn mọi cách sửa qua dòng lệnh. Nếu bạn chỉ muốn Claude đọc rồi đề xuất cách sửa chứ chưa sửa gì, bạn chuyển sang chế độ `Plan` bằng `Shift+Tab`.

Với Codex, nếu bạn chỉ muốn nó đọc file mà không được sửa gì thì bạn dùng `--sandbox read-only`. Với tuỳ chọn `--ask-for-approval on-request`, Codex hỏi bạn trước khi sửa file ngoài thư mục dự án hoặc truy cập mạng. Còn sandbox quyết định nó được đọc, sửa file và chạy lệnh ở đâu. Bạn đổi `--ask-for-approval` thành `never` thì Codex sẽ không hỏi bạn nữa, nhưng giới hạn của sandbox bạn chọn vẫn còn nguyên.

**Bước 4. Hoàn tác phần đã sửa.**

Nếu bạn không muốn giữ lời dặn mới nữa thì bạn xoá đúng đoạn vừa thêm, hoặc chép bản gốc của file hướng dẫn trở lại chỗ cũ. Với những thay đổi mà Claude làm bằng công cụ sửa file, bạn bấm `Esc` 2 lần hoặc gõ `/rewind` là quay lại được. Nhưng cách này không hoàn tác được những gì sửa bằng lệnh Bash hay bằng một chương trình khác, và cũng không hoàn tác được việc agent đã làm trên một hệ thống bên ngoài.

Hoàn tác xong thì bạn mở một phiên mới và kiểm lại file hướng dẫn như ở Bước 1. Nếu dự án của bạn đang dùng `AGENTS.md`, bạn đừng tạo thêm `CLAUDE.local.md` để thử luật, vì có file đó thì Claude Code có thể ngừng đọc `AGENTS.md`.

## 5. Kiểm tra lỗi khi dùng agent harness

- **Có luật mà agent không làm theo:** Trong Claude Code, bạn mở `/context`, xem bạn đang đứng ở thư mục nào, và tìm những file đang dặn có ý nghĩa ngược nhau. Nếu luật của bạn nằm trong `AGENTS.md`, bạn xem thêm các file `CLAUDE.md`, vì chúng có thể làm Claude bỏ qua `AGENTS.md`. Kiểm xong mấy chỗ đó rồi bạn mới sửa luật cho cụ thể hơn hoặc cắt bớt phần không cần thiết.
- **Agent vẫn làm điều bạn đã cấm:** Bạn kiểm tra xem luật đó mới chỉ nằm trong file hướng dẫn, hay đã được đặt thành luật chặn trong phần quyền. Muốn ngăn nó sửa file doanh thu gốc thì một lời dặn là không đủ. File hướng dẫn dài quá thì bạn đọc lại từ đầu, dòng nào xoá đi mà agent vẫn làm đúng thì bỏ hẳn dòng đó.
- **Agent quên điều đã chốt trong một phiên dài:** Bạn ghi những gì đã chốt vào file hướng dẫn, để phiên sau agent còn đọc lại được. Tài liệu Claude Code khuyên bạn gõ `/clear` sau 2 lần sửa mà agent vẫn chưa ra kết quả đúng, rồi viết lại yêu cầu ban đầu cho rõ hơn.
- **Agent dừng lại xin quyền, hoặc bị chặn một thao tác:** Bạn đọc kỹ nó đang xin làm gì trước khi bạn đổi quyền, vì có thể harness đang giữ đúng giới hạn bạn đặt ra. Khi bạn còn chưa hiểu nó định làm gì thì đừng mở toàn quyền chỉ để nó chạy tiếp.
- **Agent báo xong mà kết quả vẫn sai:** Bạn bảo nó chỉ ra mỗi con số trong báo cáo lấy từ dòng nào trong file doanh thu, rồi bạn tự đối chiếu lại với file gốc. Câu nào so sánh với tháng trước trong khi file không có số tháng trước thì vẫn sai, dù agent nói nó đã kiểm rồi.
- **Thông tin đủ, quyền đúng mà agent vẫn làm sai:** Lúc này nguyên nhân có thể nằm ở mô hình. Bạn thu hẹp công việc lại, chỉ giữ đúng trường hợp đang lỗi, rồi mới tính chuyện đổi mô hình hay đổi cách làm. Không phải lỗi lặp lại nào cũng do harness.

## 6. Kết luận

Khi agent lặp lại một lỗi nhiều lần, bạn cần xác định xem đang thiếu cái nào trong 3 thứ sau: một lời dặn đủ cụ thể, dữ liệu để nó làm đúng việc, hay một luật chặn hành động đó. Rồi bạn đổi từng điểm một và đối chiếu lại kết quả sau mỗi lần, vì sửa nhiều thứ cùng lúc thì bạn không biết thay đổi nào mới có tác dụng. Với ví dụ ở đầu bài, mọi con số trong bản báo cáo phải khớp với file doanh thu, còn để agent không sửa bản gốc thì bạn nên đặt một luật chặn trong phần quyền, chứ không phải chỉ trông chờ vào lời dặn.

## Nguồn tham khảo

- [Anthropic — Cách Claude Code hoạt động](https://code.claude.com/docs/en/how-claude-code-works).
- [Vivek Trivedy, LangChain — Các thành phần của agent harness](https://www.langchain.com/blog/the-anatomy-of-an-agent-harness).
- [Anthropic — Thiết kế harness cho công việc phát triển ứng dụng kéo dài](https://www.anthropic.com/engineering/harness-design-long-running-apps).
- [Anthropic — Cách Claude Code ghi nhớ dự án](https://code.claude.com/docs/en/memory).
- [Anthropic — Cấu hình quyền trong Claude Code](https://code.claude.com/docs/en/permissions).
- [Anthropic — Hướng dẫn sử dụng skill](https://code.claude.com/docs/en/skills).
- [Model Context Protocol — Giới thiệu MCP](https://modelcontextprotocol.io/docs/getting-started/intro).
- [Anthropic — Tài liệu tham chiếu hook](https://code.claude.com/docs/en/hooks).
- [OpenAI — Hướng dẫn tuỳ chỉnh bằng AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md).
- [OpenAI — Quyền phê duyệt và bảo mật của Codex](https://learn.chatgpt.com/docs/agent-approvals-security).
- [Mitchell Hashimoto — Hành trình áp dụng AI](https://mitchellh.com/writing/my-ai-adoption-journey).
- [Anthropic — Thực hành sử dụng Claude Code](https://code.claude.com/docs/en/best-practices).
- [Anthropic — Quản lý context hiệu quả cho AI agent](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).