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

> hyperresearch là một skill kèm gói Python giúp Claude Code hoặc OpenAI Codex làm nghiên cứu sâu: tìm nguồn, đọc, kiểm tra trích dẫn rồi viết báo cáo có dẫn nguồn đầy đủ. Mọi nguồn đã đọc được lưu vào một kho (vault) để lần sau dùng lại. Cài bằng pip và một lệnh install, không khó nếu bạn đã có Python 3.11 trở lên và Claude Code hoặc Codex.

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

hyperresearch là một bộ skill cho Claude Code (chạy được cả trên OpenAI Codex) để làm "nghiên cứu sâu": bạn đặt một câu hỏi, nó tự chạy một quy trình 16 bước, tìm và đọc rất nhiều nguồn rồi viết ra một báo cáo có dẫn nguồn. Phần cốt lõi là một gói Python tên `hyperresearch`, cài bằng pip.

Nếu bạn từng nhờ AI "tìm hiểu giúp mình về X" và nhận về một đoạn văn trơn tru nhưng không biết dẫn nguồn có thật không, repo này nhắm đúng chỗ đau đó. Nó bắt AI đọc nhiều nguồn, đối chiếu mâu thuẫn, rồi cho một bộ "kiểm tra viên" soi từng câu trích dẫn trước khi báo cáo được coi là xong. Hợp với người làm kinh doanh cần phân tích đối thủ, nhân viên văn phòng cần tổng hợp tài liệu, và lập trình viên muốn một công cụ nghiên cứu chạy ngay trong terminal.

Điểm đáng giá nhất: mọi nguồn nó đã đọc được lưu vào một kho tra cứu (markdown kèm SQLite) trong dự án của bạn. Lần nghiên cứu sau sẽ dùng lại kho này trước khi đi tải thứ mới. Repo hiện có khoảng 4.702 sao và 489 fork, giấy phép MIT, và vẫn được cập nhật trong 3 tháng gần đây.

```repo
- repo | jordan-gibbs/hyperresearch
- kind | Skill
- desc | Bộ skill cho Claude Code và OpenAI Codex: từ một câu hỏi, tự tìm hàng trăm nguồn, kiểm chứng trích dẫn và viết báo cáo, lưu mọi nguồn vào kho tra cứu.
- stars | 4.7k
- lang | Python
- license | MIT
```

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

Dưới đây là những tính năng chính, kèm lợi ích thực tế.

- **Đọc rất nhiều nguồn trong một lần chạy.** README nói một lần chạy có thể đạt hơn 250 nguồn. Ở mức cấu hình `premier`, riêng bước quét rộng nhắm 100–130 nguồn. Bạn không phải tự mở từng trang.
- **Kiểm tra trích dẫn trước khi giao báo cáo.** Một bộ kiểm tra "khó tính" xem nguồn được trích có thật sự ủng hộ câu văn không. Trích dẫn bịa hoặc nguồn đã bị rút lại sẽ chặn báo cáo, không cho qua.
- **Không coi bản sao là nhiều nguồn.** Nếu năm trang cùng đăng lại một thông cáo báo chí, công cụ gom chúng lại và tính là một. Báo cáo của bạn đỡ bị "ảo giác đồng thuận".
- **Bốn bộ phản biện tấn công bản nháp.** Sau đó một bộ sửa chỉ được phép chỉnh từng đoạn nhỏ, không được viết lại cả báo cáo. Nhờ vậy nội dung đã kiểm chứng không bị thay đổi lung tung ở phút cuối.
- **Tìm tài liệu học thuật qua một lệnh.** `hpr scholar search` truy vấn tám nguồn như OpenAlex, Crossref, CORE, DOAB, ClinicalTrials.gov, SEC EDGAR và FRED, rồi trả về một danh sách đã lọc trùng. Sách, thử nghiệm lâm sàng và hồ sơ doanh nghiệp đi cùng bài báo khoa học.
- **Cố đọc toàn văn bài bị chặn trả phí.** Thay vì chỉ lấy phần tóm tắt, nó thử tìm bản truy cập mở hợp pháp qua Unpaywall, Europe PMC và CORE. Mỗi lần thay thế đều được ghi chú rõ.
- **Chạy hỏng thì chạy tiếp được.** Mỗi lần chạy có một bản ghi tiến độ, và lệnh `run resume` tiếp tục đúng bước bị dừng.
- **Co giãn theo câu hỏi.** Câu hỏi ngắn, có giới hạn đi đường nhanh khoảng 30–40 phút. Câu hỏi phân tích sâu chạy đủ 16 bước, khoảng 1,5–2,5 giờ. Chế độ luận văn (thử nghiệm) có thể mất 4–8 giờ.

Ngoài ra bạn chọn được "giọng" báo cáo: giải thích cho người mới (`teach`), bản đồ toàn cảnh không phán xét (`survey`), phân tích đánh giá (`analyze`, mặc định) hoặc bảo vệ một luận điểm (`advocate`). Bước đầu tiên của quy trình tự chọn giọng dựa vào cách bạn đặt câu hỏi, và yêu cầu ghi rõ trong câu hỏi luôn được ưu tiên.

Tác giả cũng có bản chạy trên máy chủ (hyperresearch.ai) kèm API, không cần cài Claude Code hay Codex. Bài này chỉ hướng dẫn bản cài 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.** File `pyproject.toml` yêu cầu `>=3.11,<3.15`.
- **Claude Code hoặc OpenAI Codex CLI.** hyperresearch là skill chạy bên trong một trong hai công cụ này, nên bạn phải có sẵn một trong hai.
- **Một thư mục dự án.** Lệnh cài đặt chạy trong thư mục bạn chọn, và kho nguồn sẽ nằm trong đó.
- **Với Codex:** phiên làm việc phải được bật quyền ghi file và quyền truy cập mạng, vì nghiên cứu cần cả hai (xem phần cài đặt).
- **`npx`** nếu bạn chọn cách cài skill qua skills.sh.

README không nêu yêu cầu về hệ điều hành, GPU hay dung lượng ổ đĩa. README cũng không nêu chi phí dùng mô hình, nên bạn nên kiểm tra gói đăng ký Claude Code hoặc Codex của mình, vì một lần chạy đầy đủ dùng khá nhiều lượt gọi mô hình (xem lưu ý bên dưới).

```note
Một lần chạy đầy đủ có thể kéo dài vài giờ và gọi nhiều tác tử phụ song song (README nói mỗi đợt tải có 8–12 tác tử). Hãy thử bằng một câu hỏi nhỏ trước và theo dõi mức dùng của gói đăng ký Claude Code hoặc Codex, để khỏi bị bất ngờ về hạn mức hay chi phí.
```

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

```steps
- Mở thư mục dự án | Mở terminal và cd vào thư mục bạn muốn nghiên cứu trong đó
- Cài gói Python | Chạy pip install hyperresearch
- Cài skill vào công cụ | Chạy hyperresearch install (Claude Code) hoặc thêm --target codex (Codex)
- Mở công cụ và gọi skill | Gõ /hyperresearch (Claude Code) hoặc $hyperresearch (Codex) kèm câu hỏi
```

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

Hyperresearch cài theo từng dự án, nên bạn cần đứng đúng thư mục. Hãy tạo hoặc chọn một thư mục riêng cho việc nghiên cứu, rồi mở terminal tại đó. Lệnh dưới đây là ví dụ của README, bạn thay `your-project` bằng tên thư mục của mình.

```bash
cd your-project
```

### Cài gói Python

Lệnh này tải gói `hyperresearch` về máy. Nếu máy báo không tìm thấy `pip`, hãy kiểm tra Python đã cài chưa và phiên bản có nằm trong khoảng 3.11–3.14 không.

```bash
pip install hyperresearch
```

### Cài skill vào Claude Code

Đây là cách mặc định. Lệnh này đặt skill và các tác tử phụ vào dự án hiện tại.

```bash
hyperresearch install
```

Sau đó mở Claude Code trong cùng thư mục và gọi:

```text
/hyperresearch
```

Nếu Claude Code không nhận ra skill vừa cài, README khuyên bạn thoát và mở lại Claude Code trong cùng thư mục, rồi chạy lại `/hyperresearch <câu hỏi>`.

### Hoặc cài cho OpenAI Codex

Thêm cờ `--target codex`. README nói lệnh này cài skill khởi đầu, các bước thực hiện, các tác tử phụ dưới dạng custom agent, một Stop hook và một đoạn ngắn trong `AGENTS.md`.

```bash
pip install hyperresearch && hyperresearch install . --target codex
```

Codex mặc định không cho ghi file và không cho ra mạng, nên hãy khởi động Codex với cả hai quyền được bật:

```bash
codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true
```

Trong phiên Codex, gọi skill bằng:

```text
$hyperresearch
```

README cũng ghi: hỗ trợ Codex sẽ có trong bản PyPI kế tiếp, và cho đến lúc đó bạn có thể cài từ GitHub bằng lệnh dưới đây. Nếu bản pip của bạn chưa có tùy chọn `--target codex`, hãy dùng cách này.

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

Nếu muốn cài cả hai phiên bản cạnh nhau, README cho biết dùng `--target all`.

### Cách khác: cài qua plugin hoặc skills.sh

Bạn có thể cài một skill khởi đầu tên `deep-research`. Skill này tự thiết lập quy trình trong dự án ở lần dùng đầu tiên, nhưng vẫn cần đã chạy `pip install hyperresearch`.

Với Claude Code, dùng plugin:

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

Hoặc dùng skills.sh:

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

Với Codex, lệnh tương ứng là:

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

Cách gọi sau khi cài: với plugin trên Claude Code là `/hyperresearch:deep-research <câu hỏi>`, với skill là `/deep-research <câu hỏi>`. Trên Codex lần lượt là `$hyperresearch:deep-research <câu hỏi>` và `$deep-research <câu hỏi>`. README còn nói bạn có thể chỉ cần nhờ "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ó.

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

Cách đơn giản nhất là xem skill đã xuất hiện trong công cụ của bạn chưa:

1. Trên Claude Code, gõ `/hyperresearch` và xem skill có hiện trong danh sách gợi ý không. Nếu không, thoát và mở lại Claude Code trong cùng thư mục như đã nói ở trên.
2. Trên Codex, README ghi Codex chỉ nhận skill khi bắt đầu phiên. Vì vậy ở lần dùng đầu, skill khởi đầu sẽ đọc trực tiếp skill vừa cài. Từ các phiên sau, bạn có thể gõ thẳng `$hyperresearch <câu hỏi>`.
3. Sau khi chạy một câu hỏi, bạn có thể xem lệnh dưới đây để biết bước đầu tiên đã chọn thiết lập gì cho lần chạy.

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

Sau khi cài cho Codex, bạn cũng sẽ thấy các thư mục mới trong dự án, theo README: `.agents/skills/hyperresearch/`, `.hyperresearch/codex/steps/`, `.codex/agents/` và file `.codex/hooks.json`. Thấy các thư mục này là dấu hiệu cài đặt đã ghi được file.

README không mô tả một màn hình "thành công" cố định nào khác, nên cách kiểm tra chắc chắn nhất là chạy thử một câu hỏi nhỏ.

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

README phân loại câu hỏi thành ba mức: `light` (câu hỏi có giới hạn, khoảng 30–40 phút), `full` (mặc định, phân tích sâu, khoảng 1,5–2,5 giờ) và `dissertation` (thử nghiệm, phải yêu cầu rõ trong câu hỏi). Các tình huống dưới đây bám theo đó. Các câu mẫu là ví dụ do mình soạn, bạn đổi nội dung cho hợp việc của mình.

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

Bạn đang chọn giữa vài phần mềm quản lý bán hàng và không có thời gian đọc hết tài liệu từng hãng. Đây là loại câu hỏi so sánh, nên bước đầu có thể xếp vào mức `light` và đi đường nhanh. Trong Claude Code, bạn gõ:

```text
/hyperresearch So sánh ba phần mềm quản lý bán hàng cho cửa hàng nhỏ: tính năng, chi phí, điểm yếu
```

Kết quả là một báo cáo có dẫn nguồn, và mọi trang đã đọc nằm trong kho của dự án. README có các báo cáo mẫu cùng kiểu (ví dụ so sánh các hệ thống POS cho nhà hàng), bạn nên đọc thử một bản để biết đầu ra trông thế nào.

> Ngày xưa mình tin câu trả lời trôi chảy. Giờ mình chỉ tin câu nào bấm vào nguồn thấy đúng.
>
> — Ông T

### Nhân viên văn phòng tổng hợp tài liệu cho buổi họp

Sếp nhờ bạn tìm hiểu một chủ đề mới trước thứ Hai. Nếu bạn là người mới với chủ đề đó, hãy nói rõ ngay trong câu hỏi rằng bạn muốn được giải thích từ đầu. README cho biết cách đặt câu "Teach me X" sẽ cho ra bản giải thích sư phạm, còn "what's the landscape" cho ra bản đồ toàn cảnh không phán xét:

```text
/hyperresearch Giải thích cho người mới: xe điện hoạt động thế nào và thị trường gồm những bên nào
```

Bạn nhận được bản giải thích có dẫn nguồn để đọc trước buổi họp. Nếu muốn đào sâu hơn giữa chừng, README có lệnh đẩy mức suy luận lên:

```bash
hyperresearch levers set <tag> inference_depth=deep --rerender
```

Chỗ `<tag>` là mã của lần chạy, bạn lấy từ `hyperresearch run status -j`. Khi chạy lệnh này, README chưa mô tả chi tiết cách lấy thẻ ngoài việc nêu lệnh trên, nên nếu không chắc hãy xem tài liệu trong thư mục `docs/` của repo.

### Dev hoặc nhà đầu tư cần đào sâu có kiểm chứng

Bạn cần một bản phân tích nghiêm túc, ví dụ chi phí năm đầu khi chuyển sang một nền tảng dữ liệu khác, dựa trên hồ sơ doanh nghiệp và bảng giá công khai. Đây là loại câu hỏi phân tích sâu, chạy đủ 16 bước. Nếu có nhiều thời gian và muốn rộng hơn, bạn đổi cấu hình lên `premier`:

```bash
hyperresearch profile list
hyperresearch profile use premier
```

`profile list` liệt kê các cấu hình và cho biết cấu hình hiện tại. `premier` nhắm 100–130 nguồn với ngân sách đào sâu gấp đôi, mất khoảng 3–5 giờ theo README. Muốn quay về mức cơ bản (khoảng 55–80 nguồn), chạy:

```bash
hyperresearch profile use full
```

Cấu hình được nhớ theo từng dự án và vẫn giữ nguyên khi bạn cài lại.

### Sinh viên hoặc người làm nghiên cứu tìm tài liệu học thuật

Bạn cần tổng quan tài liệu về một đề tài và muốn có cả bài báo, sách lẫn dữ liệu. Skill dùng `hpr scholar search` để hỏi nhiều nguồn cùng lúc rồi lọc trùng theo DOI và tiêu đề. Với bài bị chặn trả phí, nó thử tìm bản mở hợp pháp để đọc toàn văn. Bạn chỉ cần mô tả đề tài bằng lời, kèm yêu cầu tổng quan:

```text
/hyperresearch Tổng quan tài liệu về tác động của làm việc từ xa lên năng suất, ưu tiên bài báo có phản biện
```

Kết quả là báo cáo kèm kho nguồn mà bạn có thể lọc theo DOI, tạp chí, số lần được trích dẫn hoặc tình trạng rút bài, theo mô tả trong README.

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

### Gõ /hyperresearch mà không thấy gì

Claude Code chỉ nạp skill khi khởi động. Hãy thoát, mở lại Claude Code trong đúng thư mục bạn đã chạy `hyperresearch install`, rồi thử lại. Nếu đã cài bằng `--global`, README lưu ý skill sẽ hiện ở mọi phiên, nhưng đổi lại thêm khoảng 15 dòng vào mỗi phiên.

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

Codex mặc định cấm cả hai. Hãy khởi động bằng đúng cờ trong phần cài đặt (`--sandbox workspace-write` và `network_access=true`). Đây là chỗ người mới hay quên, vì khi thiếu quyền, bước tải nguồn sẽ không chạy được.

### `--target codex` không được nhận

README ghi hỗ trợ Codex nằm trong bản PyPI kế tiếp. Nếu bản bạn cài chưa có, hãy cài từ GitHub bằng `pip install git+https://github.com/jordan-gibbs/hyperresearch` rồi chạy lại lệnh install.

### Có trang bị chặn hoặc cần đăng nhập

Trên Codex không có "làn trình duyệt", nên các trang bị chặn bằng đăng nhập hoặc chống bot sẽ nằm trong hàng chờ, và thông báo cuối liệt kê chúng cho bạn. Bạn có thể tự mở các trang đó và đưa nội dung cho công cụ nếu thật sự cần.

### Lần chạy bị dừng giữa chừng

Đừng chạy lại từ đầu. README cho biết mỗi lần chạy có bản ghi tiến độ và lệnh `run resume` tiếp tục từ đúng bước bị dừng. Trên Codex còn có một Stop hook (`hyperresearch run stop-gate`) ngăn phiên kết thúc khi quy trình đang dở.

```note
Trên Codex, chạy không tương tác bằng `codex exec` không thể hỏi bạn có tin các hook của dự án không. README nói phải thêm `--dangerously-bypass-hook-trust` thì Stop hook mới chạy, và chỉ nên dùng khi bạn đã đọc nội dung `.codex/hooks.json`. Tên cờ đã tự nói lên rủi ro, nên đừng bật nó một cách tùy tiện.
```

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

**Điểm mạnh.** Quy trình rõ ràng, có kiểm chứng trích dẫn, tách nguồn thật khỏi bản sao, và có kho nguồn tái sử dụng được. Bạn có thể đi từ câu hỏi nhanh đến phân tích sâu bằng cùng một công cụ, và cài được trên cả Claude Code lẫn Codex. Giấy phép MIT nên dùng tự do.

**Giới hạn.** Một lần chạy đầy đủ tốn nhiều giờ và nhiều lượt gọi mô hình, nên không hợp với câu hỏi nhanh kiểu "giờ này ở Tokyo là mấy giờ". Trên Codex, các khóa công cụ của bộ sửa và bộ chỉnh câu chỉ là chỉ dẫn, không phải cơ chế bắt buộc như trên Claude Code, và không có làn trình duyệt. Chế độ luận văn đang ở dạng thử nghiệm, README thừa nhận một số mục tiêu độ dài và số nguồn chưa được nối vào quy trình. README không nêu chi phí dùng mô hình, nên bạn tự theo dõi hạn mức.

**Khi nào chọn cách khác.** Nếu bạn không muốn cài gì và chỉ cần dùng ngay, README giới thiệu bản chạy trên máy chủ của tác giả (kèm API và MCP server), nhưng bài này không có thông tin về giá. Nếu chỉ cần câu trả lời ngắn có vài đường dẫn, một cuộc trò chuyện thường với AI là đủ. Còn nếu bạn cần báo cáo mà mình có thể bấm vào từng nguồn để kiểm lại, hyperresearch đáng để thử một lần với một câu hỏi nhỏ.

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

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

Repo là mã nguồn mở, giấy phép MIT, và gói Python cài bằng pip. Tuy nhiên nó chạy bên trong Claude Code hoặc Codex, nên việc dùng các công cụ đó có thể tính theo gói đăng ký của bạn. README không nêu chi phí cụ thể. Tác giả cũng có bản chạy trên máy chủ, nhưng tư liệu bài này không có thông tin về giá.

### Cần Python phiên bản nào?

File pyproject.toml yêu cầu Python từ 3.11 đến dưới 3.15, tức dùng được 3.11, 3.12, 3.13 và 3.14. README cũng ghi lại khoảng Python 3.11–3.14. Nếu máy bạn dùng phiên bản cũ hơn, hãy cập nhật Python trước khi cài.

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

Dùng được cả hai. Với Claude Code, chạy hyperresearch install. Với Codex, chạy hyperresearch install . --target codex. README nói Codex cần được mở với quyền ghi file và truy cập mạng, và bản PyPI kế tiếp mới có hỗ trợ Codex, nên có thể phải cài từ GitHub.

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

Theo README, câu hỏi có giới hạn (mức light) khoảng 30–40 phút. Phân tích sâu (mức full, mặc định) khoảng 1,5–2,5 giờ. Cấu hình premier khoảng 3–5 giờ, còn chế độ luận văn thử nghiệm khoảng 4–8 giờ.

### Có cần GPU hoặc cấu hình máy mạnh không?

README không nêu yêu cầu về GPU hay phần cứng. Phần suy luận do Claude Code hoặc Codex đảm nhận, còn hyperresearch điều phối quy trình, tải trang và lưu kho nguồn trong thư mục dự án của bạn. Về dung lượng ổ đĩa cho kho, tư liệu chưa có thông tin.

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

Theo README, mọi nguồn được lưu vào một kho dạng markdown và SQLite ngay trong dự án của bạn, và các lần chạy sau dùng lại kho đó. README cũng ghi hyperresearch không tự sửa cấu hình Codex của bạn. Về chính sách dữ liệu của Claude Code hay Codex, bạn cần xem điều khoản của nhà cung cấp.

### Khác gì việc hỏi AI bình thường?

Thay vì một lượt trả lời, nó chạy quy trình nhiều bước: quét nhiều nguồn, đối chiếu mâu thuẫn, viết nháp, cho bốn bộ phản biện soi, rồi kiểm tra từng câu trích dẫn. Nó cũng giữ lại mọi nguồn trong một kho tra cứu. Đổi lại, thời gian chạy lâu hơn nhiều so với một câu hỏi thường.
