📘 Hướng dẫn kết nối Archon vào Claude Code & Codex

🟣 Phần A — Dùng với Claude Code

1Cài Claude Code (bỏ qua nếu đã có)

Mở PowerShell (Windows) hoặc Terminal (Mac/Linux), kiểm tra:

claude --version

• Nếu ra số phiên bản → đã có, sang Bước 2.
• Nếu báo "command not found" → cài theo trang chính thức của Anthropic. Cách phổ biến (cần Node.js):

  npm install -g @anthropic-ai/claude-code

  Sau đó gõ claude lần đầu để đăng nhập tài khoản Claude của bạn.

2Thêm Archon vào Claude Code ⭐

Copy nguyên dòng dưới, dán vào PowerShell/Terminal, Enter:

claude mcp add --transport http archon "https://archon-mcp-pi.batnuocdodi.xyz/mcp" -H "Authorization: Bearer ark_df9270137cca44d41ce869abb20de1216f5d23df" -s user

💡 -s user nghĩa là Archon dùng được ở mọi project của bạn (không phải chỉ 1 thư mục).

Nếu thành công, màn hình hiện:

Added HTTP MCP server archon with URL: https://archon-mcp-pi.batnuocdodi.xyz/mcp to user config

3Kiểm tra kết nối

claude mcp list

Kết quả mong muốn (có dấu ✔ Connected):

archon: https://archon-mcp-pi.batnuocdodi.xyz/mcp (HTTP) - ✔ Connected

4Khởi động lại Claude Code

Đóng và mở lại Claude Code để nó nạp các công cụ của Archon.

Xong! Giờ bạn có thể nhờ Claude Code làm việc với Archon, ví dụ:
• "Liệt kê các task trong Archon"
• "Tạo task mới: sửa lỗi đăng nhập"
• "Đổi trạng thái task X sang doing"

🩺 Gặp lỗi? (Claude Code)

Muốn gỡ Archon ra:

claude mcp remove archon -s user

🟢 Phần B — Dùng với Codex OpenAI Codex CLI

Codex không dùng lệnh claude mcp add. Thay vào đó bạn khai báo Archon trong file cấu hình config.toml của Codex.

1Cài Codex CLI (bỏ qua nếu đã có)

Mở PowerShell (Windows) hoặc Terminal (Mac/Linux), kiểm tra:

codex --version

• Nếu ra số phiên bản → đã có, sang Bước 2.
• Nếu báo "command not found" → cài (cần Node.js 20+):

  npm install -g @openai/codex

  (Mac có thể dùng brew install codex.) Sau đó gõ codex lần đầu để đăng nhập tài khoản OpenAI của bạn.

2Khai báo Archon + token ⭐

2a. Đặt token vào biến môi trường (để không lộ token trong file config):

➤ Windows (PowerShell):

setx ARCHON_TOKEN "ark_df9270137cca44d41ce869abb20de1216f5d23df"

⚠️ Sau setx phải mở một cửa sổ PowerShell MỚI thì biến mới có hiệu lực.

➤ Mac / Linux: thêm dòng sau vào cuối ~/.zshrc (hoặc ~/.bashrc) rồi mở terminal mới:

export ARCHON_TOKEN="ark_df9270137cca44d41ce869abb20de1216f5d23df"

2b. Sửa file cấu hình Codex: ~/.codex/config.toml
Windows: C:\Users\<tên-bạn>\.codex\config.toml — nếu chưa có thì tạo mới file này.

Thêm đoạn sau vào file (nếu đã có mục [features] thì chỉ thêm dòng experimental_use_rmcp_client):

[features]
experimental_use_rmcp_client = true

[mcp_servers.archon]
url = "https://archon-mcp-pi.batnuocdodi.xyz/mcp"
bearer_token_env_var = "ARCHON_TOKEN"

💡 experimental_use_rmcp_client = true là công tắc bật hỗ trợ MCP từ xa (remote HTTP) — bắt buộc phải có, nếu không Codex sẽ không kết nối được Archon.

Cách khác (nhanh, nhưng dán token thẳng vào file): nếu bạn không muốn dùng biến môi trường ở 2a, thay bearer_token_env_var bằng:

[mcp_servers.archon]
url = "https://archon-mcp-pi.batnuocdodi.xyz/mcp"
http_headers = { "Authorization" = "Bearer ark_df9270137cca44d41ce869abb20de1216f5d23df" }

3Kiểm tra kết nối

codex mcp list

Kết quả mong muốn: có dòng archon trỏ tới https://archon-mcp-pi.batnuocdodi.xyz/mcp.

Hoặc mở Codex (gõ codex) rồi trong khung chat gõ /mcp để xem danh sách MCP đang chạy.

4Khởi động lại & dùng thử

Đóng và mở lại Codex để nạp công cụ Archon. Sau đó thử nói:

Xong! Ví dụ nhờ Codex:
• "Liệt kê các task trong Archon"
• "Tạo task mới: sửa lỗi đăng nhập"
• "Đổi trạng thái task X sang doing"

🩺 Gặp lỗi? (Codex)

Muốn gỡ Archon ra:

codex mcp remove archon

(Hoặc xoá thủ công đoạn [mcp_servers.archon] trong config.toml.)