# hyperresearch: biến Claude Code và Codex thành agent nghiên cứu sâu — hướng dẫn cài đặt và dùng

> hyperresearch là một bộ skill và gói Python (MIT) biến Claude Code hoặc OpenAI Codex thành agent nghiên cứu sâu. Bạn đưa một câu hỏi, nó tự tìm nguồn, đọc, phản biện và viết báo cáo có trích dẫn. Cài bằng pip và một lệnh install, cần Python 3.11 đến 3.14.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-05-10 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/hyperresearch-agent-nghien-cuu-sau-claude-code-codex

**hyperresearch là một bộ skill kèm công cụ dòng lệnh Python, giúp Claude Code (và cả OpenAI Codex) làm nghiên cứu sâu thay bạn.** Bạn đặt một câu hỏi, nó chạy quy trình nhiều bước: chia nhỏ câu hỏi, tìm và đọc hàng chục đến hàng trăm nguồn, viết nháp, cho nhiều "người phản biện" soi lỗi rồi mới ra báo cáo cuối.

Vấn đề nó giải quyết rất quen thuộc: hỏi AI một câu phức tạp thì được câu trả lời trôi chảy nhưng khó biết nguồn nào thật, trích dẫn nào bịa. hyperresearch buộc từng trích dẫn phải được kiểm tra xem nguồn có thật sự nói đúng câu đó không. Mọi nguồn nó đọc cũng được lưu vào một "kho" (vault) dạng markdown kèm SQLite, nên lần nghiên cứu sau không phải bắt đầu từ số không.

Repo hiện có khoảng 4712 sao và 490 fork, giấy phép MIT, vẫn được cập nhật trong 3 tháng gần đây. Bạn nên dùng nếu hay phải làm báo cáo so sánh đối thủ, khảo sát thị trường, tìm hiểu một lĩnh vực mới, hoặc tổng hợp tài liệu. Điểm đáng giá nhất là bước kiểm chứng trích dẫn và kho nguồn tích lũy qua nhiều lần chạy.

```repo
- repo | jordan-gibbs/hyperresearch
- kind | Skill
- desc | Skill cho Claude Code và OpenAI Codex: từ một câu hỏi, chạy quy trình 16 bước để ra báo cáo có trích dẫn đã kiểm chứng, nguồn lưu vào kho tra cứu.
- stars | 4.7k
- lang | Python
- license | MIT
```

## hyperresearch làm được gì

Dưới đây là các tính năng chính, giải thích theo lợi ích thực tế.

- **Quy trình 16 bước, tự chọn mức theo câu hỏi.** Câu hỏi đơn giản đi đường nhanh khoảng 30–40 phút. Câu hỏi cần lập luận sâu chạy đủ các bước, khoảng 1,5–2,5 giờ. Bạn không phải tự dựng quy trình.
- **Đọc nhiều nguồn trong một lần chạy.** README nói một lần chạy có thể thu thập hơn 250 nguồn ở cấu hình mạnh nhất. Bạn có bức tranh rộng hơn nhiều so với vài đường link AI thường dẫn.
- **Kiểm chứng từng trích dẫn trước khi giao báo cáo.** Một bước "cite-check" xem nguồn có thật sự ủng hộ câu được trích không. Trích dẫn bịa hoặc nguồn đã bị rút lại sẽ bị chặn ở cổng cuối.
- **Không coi bản sao chép là đồng thuận.** Năm trang cùng đăng lại một thông cáo báo chí chỉ được tính như một nguồn. Nhờ vậy báo cáo ít bị "thổi phồng" bởi nội dung lặp.
- **Phản biện và vá lỗi có kiểm soát.** Bốn "critic" soi bản nháp song song. Người vá chỉ được sửa từng đoạn nhỏ, không được viết lại cả báo cáo. Nhờ đó bản đã kiểm tra không bị đổi nội dung bất ngờ.
- **Tìm nguồn học thuật.** Lệnh `hpr scholar search` tìm qua tám nguồn (OpenAlex, Crossref, CORE, DOAB, ClinicalTrials.gov, SEC EDGAR, FRED…) và gộp kết quả, bỏ trùng theo DOI và tiêu đề. Có cả sách, thử nghiệm lâm sàng và hồ sơ tài chính, không chỉ bài báo.
- **Cố đọc toàn văn bài báo bị khoá.** Thay vì chỉ lưu phần tóm tắt ngắn, nó hỏi Unpaywall, Europe PMC và CORE xem có bản mở hợp pháp không. Mỗi lần thay thế đều được ghi rõ.
- **Kho tri thức dùng lại được.** Nguồn đã đọc nằm trong kho, phiên sau tra trước khi tải mới.
- **Chạy hỏng thì chạy tiếp.** Mỗi lần chạy có một bản ghi tiến trình, lệnh `run resume` tiếp tục đúng bước bị dừng.

Tác giả cũng có bản hosted (hyperresearch.ai) với API, nhưng bài này chỉ hướng dẫn bản tự chạy trên máy bạn.

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

Theo tư liệu, bạn cần:

- **Python từ 3.11 đến 3.14** (theo `pyproject.toml` và README).
- **Claude Code** hoặc **OpenAI Codex CLI** (một trong hai, hoặc cả hai). hyperresearch chạy bên trong các công cụ này, nên bạn cần cài và đăng nhập sẵn.
- Một **thư mục dự án** để cài vào. Cách cài mặc định là theo từng dự án.
- Với Codex: phiên làm việc phải được mở với quyền ghi file và quyền truy cập mạng (xem phần cài đặt).

README không nêu yêu cầu về GPU, hệ điều hành cụ thể hay API key riêng cho hyperresearch. Chi phí cũng chưa được ghi: quy trình dùng nhiều agent con chạy song song, nên hãy theo dõi hạn mức của gói Claude hoặc Codex đang dùng.

```note
Một lần chạy đầy đủ kéo dài hàng giờ và dùng nhiều agent con song song. README không ghi chi phí, nên lần đầu hãy thử với câu hỏi nhỏ và theo dõi mức tiêu thụ hạn mức của bạn.
```

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

```steps
- Mở terminal trong thư mục dự án | cd vào thư mục bạn muốn làm việc
- Cài gói Python | pip install hyperresearch
- Cài skill vào dự án | hyperresearch install (Claude Code) hoặc thêm --target codex
- Mở Claude Code hoặc Codex | chạy trong cùng thư mục, bật quyền nếu dùng Codex
- Gọi skill | /hyperresearch <câu hỏi> hoặc $hyperresearch <câu hỏi>
```

### Mở terminal đúng thư mục

Hyperresearch cài theo từng dự án, nên bạn phải đứng đúng thư mục muốn dùng. Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) rồi chuyển vào thư mục đó. Ví dụ với thư mục tên `your-project`:

```bash
cd your-project
```

Thay `your-project` bằng tên thư mục thật của bạn. Chỗ này người mới hay vấp: cài ở thư mục này mà mở Claude Code ở thư mục khác thì sẽ không thấy skill.

### Cài gói Python

```bash
pip install hyperresearch
```

Lệnh này tải công cụ `hyperresearch` về máy. Nếu báo không tìm thấy `pip` hoặc Python quá cũ, xem phần lỗi thường gặp bên dưới.

### Cài skill vào dự án

Chọn đúng lệnh theo công cụ bạn dùng:

```bash
hyperresearch install                    # Claude Code, then: /hyperresearch

hyperresearch install . --target codex   # OpenAI Codex, then: $hyperresearch
```

Còn nếu muốn cả hai chạy song song, README nói dùng `--target all`:

```bash
hyperresearch install . --target all
```

Với Codex, lệnh install đặt skill vào `.agents/skills/hyperresearch/`, các bước quy trình vào `.hyperresearch/codex/steps/`, các agent con vào `.codex/agents/`, một Stop hook vào `.codex/hooks.json` và một đoạn ngắn vào `AGENTS.md`.

Ngoài ra README ghi một lựa chọn cho người dùng nâng cao: `hyperresearch install --global` giúp `/hyperresearch` dùng được ở mọi phiên Claude Code, nhưng đổi lại mỗi phiên sẽ thêm khoảng 15 dòng vào system reminder. Nếu không chắc, cứ cài theo từng dự án như trên.

### Cách khác: cài qua plugin hoặc skill

README còn có hai đường khác, đều cài một skill khởi động tên `deep-research` rồi tự thiết lập quy trình lúc dùng lần đầu. Cả hai vẫn cần `pip install hyperresearch`.

Plugin trong Claude Code:

```bash
/plugin marketplace add jordan-gibbs/hyperresearch
/plugin install hyperresearch@hyperresearch
```

Plugin trong Codex:

```bash
codex plugin marketplace add jordan-gibbs/hyperresearch
codex plugin add hyperresearch@hyperresearch
```

Hoặc cài skill đơn qua skills.sh:

```bash
npx skills add jordan-gibbs/hyperresearch -a claude-code
npx skills add jordan-gibbs/hyperresearch -a codex
```

Với cách này, lệnh gọi sẽ là `/hyperresearch:deep-research <câu hỏi>` (plugin) hoặc `/deep-research <câu hỏi>` (skill) trên Claude Code. Trên Codex thì thay `/` bằng `$`.

### Nếu dùng Codex: mở phiên với quyền ghi và mạng

Quá trình nghiên cứu cần ghi file và ra mạng, mà Codex mặc định không cho cả hai. Hãy mở Codex bằng lệnh sau:

```bash
codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true
# then, in the session:
$hyperresearch
```

README cũng ghi chú rằng bản hỗ trợ Codex sẽ có trong bản PyPI kế tiếp. Trước đó, bạn có thể cài thẳng từ GitHub:

```bash
pip install git+https://github.com/jordan-gibbs/hyperresearch
```

Hyperresearch không tự sửa cấu hình Codex của bạn. Các quyền này chỉ truyền qua cờ lệnh.

### Gọi skill lần đầu

Trong Claude Code gõ `/hyperresearch` kèm câu hỏi. Trong Codex gõ `$hyperresearch` kèm câu hỏi. README nói bạn cũng có thể chỉ cần yêu cầu "nghiên cứu sâu" bằng lời thường, skill sẽ tự kích hoạt theo mô tả của nó.

Nếu Claude Code chưa nhận skill và agent mới cài, hãy khởi động lại nó ở cùng thư mục rồi chạy lại `/hyperresearch <câu hỏi>`.

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

Cách nhanh nhất là gọi một lệnh của chính công cụ để xem nó có phản hồi không:

```bash
hyperresearch profile list
```

Lệnh này liệt kê các "gear" (mức quy mô), kèm mô tả và gear hiện tại. Thấy danh sách là gói Python đã cài được.

Tiếp theo, kiểm tra phần skill:

- Trên Claude Code: gõ `/hyperresearch` trong phiên, nếu skill được nhận là cài xong.
- Trên Codex: kiểm tra có thư mục `.agents/skills/hyperresearch/` và file `.codex/hooks.json` trong dự án.

Khi đang chạy hoặc sau khi chạy, xem tiến trình và lựa chọn của bước 1 bằng:

```bash
hyperresearch run status -j
```

Báo cáo cuối được ghi ở `final_report.md` theo mô tả trong README, còn câu hỏi gốc được lưu trong thư mục `research/runs/` của dự án.

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

### Chủ quán so sánh phần mềm bán hàng

Bạn mở quán và đang phân vân giữa vài phần mềm quản lý bán hàng. Trong Claude Code, bạn gõ câu hỏi bằng lời thường, ví dụ:

```text
/hyperresearch So sánh các hệ thống POS cho nhà hàng nhỏ: chi phí, tính năng, rủi ro hợp đồng
```

Đây là câu mẫu do mình đặt, bạn tự thay bằng chủ đề của bạn. Vì là câu hỏi so sánh, bước 1 có thể xếp vào mức `light` và đi đường nhanh. Kết quả là một báo cáo có trích dẫn cho từng nhận định. README có đưa mẫu cùng kiểu (phân tích đối thủ POS cho nhà hàng) từ bản hosted để bạn xem trước chất lượng.

### Nhân viên văn phòng tìm hiểu một lĩnh vực mới

Sếp giao bạn "tìm hiểu thị trường X" trong khi bạn chưa biết gì. Bạn có thể nói rõ kiểu báo cáo mình cần ngay trong câu hỏi, vì README nói bước 1 chọn "register" từ cách bạn đặt câu:

- "Dạy mình về X" ra bản giải thích kiểu giảng bài (`teach`).
- "Toàn cảnh lĩnh vực X" ra bản bản đồ lĩnh vực, không phán xét (`survey`).

Nếu cần đi sâu hơn giữa chừng, README có lệnh đổi mức:

```bash
hyperresearch levers set <tag> inference_depth=deep --rerender   # go deeper mid-run
```

Bạn nhận được một báo cáo đúng giọng bạn cần, thay vì tự đọc hàng chục tab.

> Trích dẫn nào cũng phải qua một người hoài nghi trước khi báo cáo được giao.
>
> — Ông T

### Dev hoặc nhà nghiên cứu cần tài liệu học thuật

Bạn cần tìm bài báo, thử nghiệm lâm sàng hoặc hồ sơ tài chính về một chủ đề. Lệnh tìm học thuật của repo gom tám nguồn vào một danh sách đã bỏ trùng:

```bash
hpr scholar search
```

README không ghi đầy đủ tham số của lệnh này trong đoạn mình có, nên hãy xem hướng dẫn trong repo (thư mục `docs/`) để biết cách truyền từ khoá. Khi chạy trong quy trình, các bài bị khoá sẽ được thay bằng bản mở hợp pháp nếu tìm thấy, và việc thay thế được ghi rõ trong ghi chú.

### Người dùng Codex chạy tự động không cần ngồi canh

Bạn muốn chạy một lần không tương tác. README cho lệnh sau, nhưng lưu ý cờ `--dangerously-bypass-hook-trust` chỉ nên dùng khi bạn đã đọc `.codex/hooks.json`:

```bash
codex exec --sandbox workspace-write -c sandbox_workspace_write.network_access=true \
  --dangerously-bypass-hook-trust "\$hyperresearch
"
```

Nếu không có cờ đó, Stop hook (lớp chặn Codex bỏ bước) sẽ không chạy, vì `codex exec` không hỏi được bạn có tin tưởng hook hay không.

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

### Không tìm thấy lệnh hyperresearch hoặc pip báo lỗi

Thường do Python chưa cài hoặc sai phiên bản. Gói yêu cầu Python từ 3.11 đến 3.14. Kiểm tra phiên bản Python bằng `python --version`, cài lại nếu ngoài khoảng đó, rồi chạy lại `pip install hyperresearch`. Nếu vừa cài xong mà vẫn không gọi được lệnh, hãy đóng và mở lại terminal.

### Claude Code không thấy skill vừa cài

README hướng dẫn khởi động lại Claude Code ở đúng thư mục đã cài rồi chạy `/hyperresearch <câu hỏi>`. Hãy chắc chắn bạn đang ở đúng dự án, vì cài mặc định là theo từng thư mục.

### Codex không ghi được file hoặc không ra mạng

Codex mặc định không cho cả hai. Mở lại phiên bằng đúng hai cờ trong phần cài đặt (`--sandbox workspace-write` và `network_access=true`). Đừng bật thêm quyền nào khác mà bạn không hiểu.

### Codex đi tắt, trả lời thẳng rồi dừng

Đây chính là việc Stop hook được thiết kế để chặn, nhưng Codex chỉ chạy hook của dự án sau khi bạn tin tưởng chúng. Trong phiên tương tác, hãy xác nhận tin tưởng hook sau khi đọc `.codex/hooks.json`. Với `codex exec`, hook không chạy nếu thiếu cờ bỏ qua bước tin tưởng.

### Một số trang không tải được

Trang đòi đăng nhập hoặc chặn bot sẽ làm bước tải nguồn thất bại. Trên Codex không có "làn trình duyệt" như Claude-in-Chrome, nên các nguồn này nằm lại trong hàng đợi và tin nhắn cuối liệt kê chúng cho bạn. Bạn có thể tự mở và đọc thủ công những nguồn đó nếu chúng quan trọng.

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

**Điểm mạnh.** Quy trình có cấu trúc rõ, kiểm chứng trích dẫn, chống nguồn lặp, kho nguồn dùng lại được và chạy lại được khi bị dừng giữa chừng. Cài đặt khá đơn giản: một lệnh pip và một lệnh install. Giấy phép MIT, chạy ngay trong công cụ bạn đã dùng.

**Giới hạn.** Chạy lâu: đường nhanh cỡ 30–40 phút, đường đầy đủ 1,5–2,5 giờ, chế độ premier có thể 3–5 giờ. Chi phí hạn mức chưa được README nêu. Trên Codex, việc "khoá công cụ" chỉ là chỉ dẫn chứ không bị ép cứng, và không có làn trình duyệt. Chế độ dissertation (báo cáo rất dài) vẫn đang ở mức thử nghiệm, README tự ghi một số chỉ tiêu chưa được nối vào hệ thống.

**Khi nên chọn cách khác.** Nếu chỉ cần câu trả lời nhanh cho một câu hỏi đơn giản, cứ hỏi AI bình thường. Nếu không muốn cài gì, tác giả có bản hosted tại hyperresearch.ai (có API) nhưng đó là dịch vụ riêng, README chưa nói rõ về giá trong phần mình có. Và với bất kỳ báo cáo quan trọng nào, bạn vẫn nên tự mở vài nguồn trọng yếu ra kiểm tra lại.

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

### hyperresearch có miễn phí không?

Repo dùng giấy phép MIT nên bạn cài và dùng gói tự chạy được mà không phải trả phí cho chính repo. Tuy nhiên nó chạy bên trong Claude Code hoặc Codex, nên vẫn tiêu hao hạn mức hoặc chi phí của các công cụ đó. README chưa ghi con số chi phí cụ thể.

### Cần cài những gì trước khi dùng?

Bạn cần Python từ 3.11 đến 3.14 và một trong hai công cụ là Claude Code hoặc OpenAI Codex CLI. Sau đó cài gói bằng pip rồi chạy lệnh hyperresearch install trong thư mục dự án. README không nêu yêu cầu GPU.

### Dùng được với Codex không, hay chỉ Claude Code?

Dùng được cả hai. Với Codex, cài bằng hyperresearch install . --target codex rồi mở phiên có quyền ghi file và truy cập mạng. Trên Codex không có làn trình duyệt và việc khoá công cụ chỉ là chỉ dẫn, không bị ép cứng.

### Chạy một lần mất bao lâu?

Câu hỏi đơn giản đi đường nhanh, khoảng 30–40 phút. Câu hỏi cần phân tích sâu chạy đủ 16 bước, khoảng 1,5–2,5 giờ ở mức mặc định. Gear premier tốn khoảng 3–5 giờ.

### Trích dẫn trong báo cáo có đáng tin không?

Quy trình có bước cite-check kiểm tra xem từng nguồn có thật sự ủng hộ câu được trích không, và trích dẫn bịa là lỗi chặn ở cổng cuối. Dù vậy README không cam kết tuyệt đối, nên với báo cáo quan trọng bạn vẫn nên tự kiểm tra các nguồn then chốt.

### Dữ liệu và nguồn đã đọc được lưu ở đâu?

Nguồn được lưu trong một kho cục bộ gồm file markdown và SQLite trong dự án của bạn, và các lần chạy sau tái sử dụng kho này. Câu hỏi gốc cũng được lưu trong thư mục research/runs/. Quy trình vẫn gọi mô hình Claude hoặc Codex và tải nội dung từ web, README chưa có phần nào nói về quyền riêng tư vượt ngoài điều đó.

### Khác gì bản hosted hyperresearch.ai?

Bản hosted dùng cùng quy trình nhưng không cần cài Claude Code hay Codex, và có thêm REST API, MCP server từ xa và API kiểm chứng trích dẫn. Bản trong repo này là bản tự chạy trên máy bạn. README chưa nêu giá của bản hosted.
