Chuyển đến nội dung chính
Blog

Hướng dẫn AgentKitBài 21/21

AK Vault: cất secret cho agent xài mà agent không thấy

24 phút đọc
Bài 21 trong bộ onboarding AgentKit v3. Đọc khoảng 15 phút. Bài này là bản hướng dẫn đầy đủ, đi sâu hơn bài 6: từ lý do cần vault, cách dùng bằng CLI và app desktop, dashboard vault.agentkit.best, đồng bộ nhiều máy, tới mấy nguyên tắc thiết kế mà bạn phải nắm để khỏi bị "vault chặn hoài, bực quá tắt luôn" 😅

Nói trước cho công bằng: vault không phải thuốc tiên. Nó giải quyết đúng một bài toán, là agent dùng được key mà không cầm được key. Nó không cứu được bạn khi bạn tự dán key vô khung chat, và cũng không cứu được một chương trình đã nhận key rồi đem đi đâu đó. Mấy giới hạn này tui ghi rõ ở mục 9.

Mọi lệnh trong bài được dán từ --help thật của ak 3.0.0, chạy trong một HOME tạm. Phần đồng bộ và dashboard đọc từ mã nguồn, tài liệu và trang công khai vault.agentkit.best ngày 04/20/2026.

1/ Tại sao cần vault: số liệu chứ không phải cảm giác

Tui hay nghe "máy tui, repo private, lo gì". Vậy xem số liệu nghen.

Rò rỉ secret đang tăng, và AI làm nó tăng nhanh hơn. Báo cáo State of Secrets Sprawl 2026 của GitGuardian (dữ liệu năm 2025):

  • 28,65 triệu secret hardcode mới bị đẩy lên GitHub public trong năm 2025, tăng 34% so với năm trước, mức tăng lớn nhất họ từng ghi nhận.

  • Secret của các dịch vụ AI (OpenAI, Anthropic, Gemini...) đạt 1.275.105, tăng 81%.

  • Commit có Claude Code hỗ trợ có tỉ lệ lộ secret 3,2%, gấp đôi mức nền 1,5%.

  • 24.008 secret nằm trong file cấu hình MCP trên GitHub public, trong đó 2.117 cái còn xài được.

  • Hơn 64% secret xác nhận còn hiệu lực từ 2022 vẫn còn hiệu lực khi kiểm tra lại tháng 01/2026. Lộ rồi mà hổng ai xoay key.

  • Repo nội bộ có khả năng chứa secret hardcode cao gấp khoảng 6 lần repo public. Vậy là "repo private" hổng phải tấm khiên đâu.

Agent đọc .env dù bạn dặn đừng đọc. The Register (01/2026) thử Claude Code v2.1.12: file .env có trong ignore mà agent vẫn đọc và in secret ra console. Một bài blog tháng 04/2026 kể chuyện AGENTS.md ghi rõ "không đọc file này" mà agent vẫn đọc. Bên Cursor, nhân viên của họ xác nhận trên forum rằng .cursorignore chặn index nhưng không chặn được lệnh terminal như cat hay grep mà agent tự chạy.

Kẻ tấn công đã biết xài chính con agent của bạn. Vụ s1ngularity (Nx, 08/2025): các bản Nx độc trên npm gọi thẳng CLI của Claude, Gemini, Q với cờ kiểu --dangerously-skip-permissions, --yolo để lùng secret trên máy. GitGuardian đếm được 2.349 credential bị lấy từ 1.079 máy dev, phần lớn là GitHub token, kèm npm, AWS, OpenAI, Anthropic key.

Prompt injection lấy secret qua tool. General Analysis (07/2025) dựng demo: chèn lệnh vào một support ticket, agent Cursor nối Supabase MCP đọc ticket, truy vấn bảng integration_tokens rồi ghi token ngược vào ticket cho kẻ tấn công đọc. Supabase phản biện là chưa có khách hàng nào bị thật, và demo chạy với cấu hình quyền cao. Hai chiều đều đúng: bug là ở cấu hình quyền, nhưng cấu hình quyền cao là chuyện dev làm hằng ngày.

Rút ra một câu: chỗ nào agent đọc được file, chỗ đó secret dạng plaintext là secret đã lộ một nửa. Vault không ngăn bạn dại, nhưng nó lấy plaintext ra khỏi tầm tay agent.


2/ AK Vault là gì

AK Vault là tên gọi chung cho hai lớp:

Lớp Là gì Trạng thái
Vault cục bộ ak secrets Cất secret trong keychain của hệ điều hành (hoặc file mã hoá age), agent xin quyền, bạn duyệt, mọi lần đọc có sổ ghi ✅ đã ship trong ak 3.0.0
Đồng bộ E2E ak secrets sync, ak secrets devices Đồng bộ vault giữa các máy, server chỉ giữ ciphertext 🧪 preview, ẩn khỏi danh sách lệnh trong --help tổng, chưa GA
Dashboard web vault.agentkit.best/app Trình duyệt là một thiết bị của vault, giải mã ngay trong trang 🧪 pre-release
Remote MCP vault.agentkit.best/mcp Cho AI tool trên cloud (ChatGPT, Claude...) tìm và dùng secret qua một máy của bạn 🧪 pre-release
Trang Secrets trong app desktop AgentKit Giao diện của vault cục bộ: thêm, duyệt, xem audit ✅ có trong app desktop 3.0.0

Cách nó vận hành, gói gọn trong một vòng:

agent viết ${secret:TEN} vào lệnh
→ hook secrets-inject gọi ak secrets resolve
→ resolve nhận diện agent bằng cách hash binary của nó
→ có grant khớp? có: thế giá trị vào, ghi audit
không: TỪ CHỐI, gửi yêu cầu vào hộp chờ
→ bạn trả lời trong terminal của bạn (ak secrets approve) hoặc app desktop

Agent chỉ thấy cái tên ${secret:TEN}. Giá trị được thế vào lúc chạy, trong bộ nhớ.


3/ Dùng bằng CLI, từng bước

Bước 1: chuyển .env vào vault

Nhập .env vào vault

Xem trước kế hoạch, rồi mới import:

ak secrets import-env ./my-app --dry-run   # thư mục: tìm .env và .env.*, sâu tối đa 3 cấp
ak secrets import-env ./my-app
ak secrets import-env .env.production # hoặc một file

Vài điều --help ghi rõ mà bạn nên biết:

  • Giá trị không bao giờ được in, log hay đưa vào --json, chỉ có số lượng import/bỏ qua.

  • Key đã có trong vault thì bị bỏ qua, trừ khi bạn thêm --force.

  • Khi import cả thư mục, nó bỏ qua .env.example, .env.template, .env.bak, symlink, thư mục ẩn và thư mục dependency. Một key có ở hai file là xung đột, bị bỏ qua ở mọi nơi, không file nào âm thầm thắng.

  • Môi trường lấy từ tên file (.env.production → production), project lấy từ thư mục.

  • import-env không đụng tới file gốc. Import xong bạn phải tự dọn .env. Không dọn là coi như chưa làm 😁

Bước 2: thêm, tìm, kiểm tra

ak secrets set OPENAI_API_KEY                       # nhập qua prompt không hiện chữ
echo -n "$VALUE" | ak secrets set OPENAI_API_KEY --value=- # hoặc pipe từ stdin
ak secrets list
ak secrets search stripe --environment production --json
ak secrets describe OPENAI_API_KEY --json # profile đầy đủ, không bao giờ có giá trị
ak secrets get OPENAI_API_KEY # giá trị hiện [redacted]

set từ chối --value=<giá trị> trên dòng lệnh, vì nó sẽ lọt vào lịch sử shell và ps.

Muốn biết key trong vault có đúng là key trong .env cũ không mà không in ra:

ak secrets compare OPENAI_API_KEY --value-file ./key-can-kiem-tra.txt

Kết quả chỉ là match hoặc differs. Giá trị dưới 16 ký tự (không tính tiền tố công khai như sk_live_) bị từ chối, và mỗi lần so là một dòng trong audit, nên đừng hòng so vòng lặp để đoán key.

Gắn thêm thông tin cho dễ tìm và nhắc xoay key:

ak secrets set STRIPE_API_KEY --force --rotate-ttl 30d --provider stripe
ak secrets rotate STRIPE_API_KEY

Bước 3: cho agent dùng

Agent viết tham chiếu, không viết giá trị:

curl -H "Authorization: Bearer ${secret:OPENAI_API_KEY}" https://api.openai.com/v1/models

Hook secrets-inject (có sẵn trong core kit) chỉ quét Bash.command và WebFetch.url. Lần đầu, chưa có grant, lệnh bị từ chối và yêu cầu nằm chờ bạn.

Agent cũng có thể xin trước khi dùng:

ak secrets request OPENAI_API_KEY --purpose "deploy billing" --json

request không bao giờ đọc giá trị, không tự ghi grant. Nó chỉ bỏ thư vào hộp chờ.

Bước 4: bạn duyệt, trong terminal của bạn

Luồng duyệt: bạn duyệt ở terminal của bạn
ak secrets approve                                   # xem lần lượt mọi yêu cầu đang chờ
ak secrets approve OPENAI_API_KEY --state once # cho đúng 1 lần
ak secrets approve OPENAI_API_KEY --state ttl --ttl 30d
ak secrets approve OPENAI_API_KEY --state deny

Bốn câu trả lời, nhớ kỹ:

Câu trả lời (--state) Nghĩa
deny Từ chối lần này, không lưu gì, lần sau nó hỏi lại
once Cho đúng một lần đọc
ttl (mặc định) Cho trong một khoảng, tự hết hạn. Mặc định 24h, đổi bằng --ttl 12h, 30d, 2w
persist Cho tới khi bạn tự revoke

Bước 5: chạy một chương trình với secret (exec scope)

Khi chỉ muốn một chương trình nhận secret trong một biến môi trường:

ak secrets run --env STRIPE_API_KEY=STRIPE_API_KEY -- stripe customers list
ak secrets run --env GH_TOKEN=GH_TOKEN --purpose release -- gh release list

Mỗi cặp VAR=REF cần một exec grant ghim đúng đường dẫn thật (đã gỡ symlink) và hash nội dung của chương trình. Chưa có thì yêu cầu được gửi vào hộp chờ, bạn trả lời bằng ak secrets approve --env STRIPE_API_KEY. Chương trình được chạy thẳng, không qua shell; shell và launcher bị từ chối; môi trường được dựng lại từ đầu (PATH hệ thống, vài biến như HOME, LANG, cộng biến được cấp); output được gạch bỏ giá trị trước khi trả về.

Bước 6: xem ai đọc gì, rút quyền khi cần

ak secrets grants
ak secrets audit --secret OPENAI_API_KEY
ak secrets audit --decision deny --json
ak secrets revoke OPENAI_API_KEY --agent sha256:<fingerprint>
ak secrets revoke --agent sha256:<fingerprint> --all # nút hoảng loạn
ak secrets trust claude # xem binary đang được tin
ak secrets trust claude --refresh # ghim lại sau khi update agent

revoke rút quyền, không rút được bản agent đã đọc. --help dặn thẳng: revoke là bước một, ak secrets rotate <ref> là bước hai.

Bước 7 (tuỳ chọn): một tên biến, nhiều tài khoản

ak secrets alias set CLAUDE_API_KEY CLAUDE_API_KEY_1   # xài tài khoản 1
ak secrets alias set CLAUDE_API_KEY CLAUDE_API_KEY_2 # đổi sang tài khoản 2
ak secrets alias list --json

Alias không cấp quyền gì. Grant phải cấp cho secret đích (CLAUDE_API_KEY_1), và alias không đồng bộ giữa các máy.

Để agent tự làm đúng: skill ak-vault

Trong Claude Code hoặc Codex:

/ak-vault import các file .env của project này vào vault rồi đổi config sang ${secret:...}

Skill đọc lựa chọn bạn đã ghi (ak config prefs resolve --json, khoá secretStore.choice) trước. Nếu bạn chọn giữ .env hay xài 1Password thì nó làm theo, không dụ bạn xài vault. Nó không bao giờ in giá trị, chỉ hỏi tối đa một lần, và với các lệnh bị chặn dưới agent thì nó đưa lệnh cho bạn tự chạy chứ không tìm đường lách.


4/ Dùng bằng app desktop

Mở app bằng ak gui (hoặc tải app desktop tại agentkit.best/agentkit-app). Trang Secrets nằm trong nhóm System, và chỉ có trong app desktop; dashboard trình duyệt mở bằng ak config start không có trang này.

Những việc làm được:

  • Add secret, Rotate, Delete, Import .env. Import mặc định chỉ thêm tên chưa có; bật Replace names that already exist thì phải xem preview trước.

  • Reveal bắt bạn nhập lý do, lý do vào audit. Copy xong thì clipboard bị xoá khi đóng dialog.

  • Export không xuất từ cửa sổ. Nó chỉ đưa lệnh ak secrets export để bạn chạy trong terminal.

  • Panel Grants liệt kê agent nào đọc được tên nào, kèm Exec scope (biến, đường dẫn, hash ngắn). Cấp và rút grant bằng tay vẫn là việc của terminal.

  • Panel Waiting for you: trả lời yêu cầu agent đang chờ.

Dialog duyệt có 4 nút: Deny, Allow once, Allow for a while (15 phút, 1 giờ mặc định, hoặc 8 giờ), Always allow. Phím tắt D, O, S, A chỉ "lên đạn" sau khoảng 0,6 giây, để một phím bạn đang gõ dở cho cửa sổ khác không lỡ trả lời một yêu cầu bạn chưa đọc. Deny là nút được focus sẵn. Decide later hoặc Esc thì để yêu cầu nằm chờ tiếp.

Để ý: "for a while" trên desktop mặc định 1 giờ, còn ak secrets approve trong terminal mặc định 24 giờ. Cùng tên, khác số. Job dài thì chọn trong terminal với --ttl cho chắc.

Thêm vài thứ đáng giá:

  • Mỗi lần secret được nhả cho agent, app hiện thông báo trong app, kèm nút Revoke this agent's grants. Cửa sổ không focus thì có thông báo hệ điều hành Secret released (không bao giờ kèm giá trị hay purpose).

  • Audit log lọc theo tên, quyết định (Allowed/Blocked/Denied) và nguồn (Agent/Terminal/Desktop). Cùng một sổ với ak secrets audit.

  • Panel Vault sync chỉ đọc: trạng thái đồng bộ, xung đột, thiết bị. Mọi thao tác sync vẫn là lệnh terminal, panel đưa sẵn nút copy lệnh.

  • Nếu chính agent mở app desktop, app từ chối câu trả lời và ghi là deny.


5/ Những tình huống hay gặp

Tình huống Làm sao
Repo cũ đầy .env ak secrets import-env ./ --dry-run → import → dọn .env → sửa config sang ${secret:TEN}
Agent gọi API bằng curl Viết ${secret:TEN} trong lệnh, duyệt lần đầu bằng approve --state ttl
Deploy bằng CLI của nhà cung cấp (stripe, gh, wrangler...) ak secrets run --env VAR=REF -- <chương-trình>, duyệt exec scope
Nhiều tài khoản Claude/OpenAI ak secrets alias set để đổi qua lại
Nghi agent đọc lung tung ak secrets audit --since 24h, rồi revoke --all + rotate
Update Claude Code xong bị từ chối hết Binary đổi hash, chạy ak secrets trust claude --refresh trong terminal của bạn
Kiểm key trong .env cũ còn khớp không ak secrets compare REF --value-file <file>
Server/container không có keychain --backend=file (vault mã hoá age), xem ak secrets recovery
Muốn secret theo qua máy thứ hai Đồng bộ 🧪 ở mục 7, chỉ với key dev/test

6/ Dashboard vault.agentkit.best 🧪

vault.agentkit.best

Trang chủ vault.agentkit.best là landing page kèm guide, how-it-works, security và FAQ. Trang tự ghi trạng thái: giao thức v1 được chủ sản phẩm review, không phải review độc lập, và cloud sync là pre-release.

Dashboard /app (pre-release, không dành cho credential production):

  • Trình duyệt là một thiết bị của vault, giống laptop thứ hai. Nó tạo device key ngay trong trình duyệt, cất trong IndexedDB dạng không xuất được, và giải mã ngay trong trang. Server vẫn chỉ nhận ciphertext.

  • Không có passphrase: mỗi lần vào là một lần đăng nhập mới. Lock hoặc rời trang là xoá phiên và bản giải mã khỏi bộ nhớ.

  • Lần đầu đăng nhập, trang hiện mã join bắt đầu bằng akj1-. Bạn chạy ak secrets devices approve <join code> trên một máy đã sở hữu vault, so mã 6 số trên hai màn hình, khớp mới bấm y.

  • Làm được: liệt kê, lọc, tìm tên, đặt giá trị, xoá, xem lịch sử revision có chữ ký, khôi phục bản cũ thành revision mới, giải xung đột. Tab Members and access chỉ đọc.

  • Không bao giờ hiện, copy hay lưu giá trị: ô giá trị là ô chỉ ghi, lưu xong là xoá.

  • Chỉ chủ vault mới thêm trình duyệt được; editor của vault chia sẻ thì không.

  • Có panel duyệt yêu cầu từ xa: Allow once, Allow for 15 phút / 1 giờ / 8 giờ, hoặc Deny. Câu trả lời được trình duyệt ký, máy yêu cầu kiểm chữ ký trước khi dùng.

Remote MCP /mcp (pre-release): thêm https://vault.agentkit.best/mcp vào phần connector của AI tool, đăng nhập AgentKit và chọn scope:

  • vault-mcp:read: thấy tên và mô tả, không thấy giá trị;

  • vault-mcp:write: thêm, thay, xoá; ghi được nhưng không đọc lại được;

  • vault-mcp:use: xin dùng secret và chạy lệnh bạn đã duyệt trên máy bạn.

Muốn đọc và dùng thì phải có một máy của bạn đang chạy ak secrets sync now --watch --relay. Không có máy nào online thì trả no_device_online. Lệnh --relay bị từ chối nếu agent chạy nó.

⚠️ Remote MCP không phải E2E. Trong lúc gọi, plaintext đi qua bộ nhớ của server sau khi TLS kết thúc (không lưu, không log, theo ADR 0002). Cần "server không bao giờ thấy plaintext" thì đừng xài remote MCP. Và đừng bao giờ dán secret vào chat cho AI tool: dùng luồng secrets_prepare_write để tự gõ giá trị trên dashboard.

Ngắt kết nối: vào tài khoản AgentKit, Connected apps, ngắt AgentKit Vault (AI tools).


7/ Nhiều máy và đồng bộ đám mây 🧪

Ghép cặp thiết bị thứ hai

Đồng bộ là opt-in. Tắt sync thì ak secrets không gửi request mạng nào. resolve luôn đọc kho cục bộ, không bao giờ chờ mạng.

Máy thứ nhất:

ak login
ak secrets sync enable --recovery-kit-out ./vault-recovery-kit.txt
ak secrets sync status

Bạn chọn mật khẩu vault và nhận một recovery key. Cất cả hai ngoài máy (giấy, password manager). Mất hết thiết bị, mật khẩu và recovery key là mất vault, server không cứu được, vì đó chính là ý nghĩa của zero-knowledge.

Máy thứ hai (3 bước, phải là bạn ngồi ở terminal):

# trên máy mới
ak secrets devices add --label laptop # in ra join code
# trên máy đã đồng bộ
ak secrets devices approve <join code> # in ra offer code
# quay lại máy mới
ak secrets devices add --offer <offer code> # hiện mã 6 số, so với máy kia

Hai máy hiện cùng mã 6 số thì mới trả lời y. Join code và offer code không phải bí mật, nhưng duyệt thì phải là bạn: devices approve và devices add --offer từ chối khi agent chạy (exit 6).

Đồng bộ hằng ngày:

ak secrets sync now
ak secrets sync now --watch # đồng bộ liên tục
ak secrets devices list

Mất máy:

ak secrets devices remove <device-prefix> --reason lost

Gỡ thiết bị sẽ xoay vault key để máy đó không đọc được thay đổi sau này. Nhưng nó không lấy lại được những gì máy đó đã giải mã. Rotate key ở phía nhà cung cấp, rồi ak secrets rotate. ak secrets list sẽ đánh dấu ref nào máy bị gỡ từng đọc được.

Còn có sync recover, sync rotate-recovery, sync settle (giải xung đột), sync disable, devices rotate.

Cảnh báo phải đọc (từ README ak-vault): sync chưa GA, đừng cất credential production. API sync production đã bật dạng preview theo quyết định của chủ sản phẩm, review là của chủ sản phẩm chứ chưa có bên thứ ba. Tui thử với key dev/test, còn key production đợi qua release gates.


8/ Nguyên tắc thiết kế bạn phải nắm

Đây là phần làm nhiều người bực nhất, vì vault "khó tính". Nhưng khó tính có lý do.

8.  1 Agent không bao giờ thấy giá trị

list, search, describe, get chỉ trả metadata và một hint (tiền tố công khai + 4 ký tự cuối). get --reveal đòi terminal tương tác ở cả stdin lẫn stdout, đòi xác nhận y/N, và không chạy trong --json hay khi pipe. Agent kiểm tra bằng exit code, hint và compare.

8.  2 Fail-closed: thiếu grant là từ chối, không phải hỏi

Hook không có terminal để hỏi bạn. --help của approve giải thích: một hook hỏi mà treo thì sẽ bị lờ đi chứ không được tuân theo, nên nó ghi yêu cầu vào hộp chờ và từ chối (exit 8). Nghĩa là lần đầu agent đụng secret mới, lệnh sẽ fail. Đó là đúng thiết kế, không phải bug.

8.  3 Duyệt phải là bạn, ở terminal của bạn

approve và grant từ chối chạy khi có agent nằm phía trên trong cây tiến trình, và ghi lần thử đó vào audit. Lý do theo nguyên văn --help: agent tự trả lời yêu cầu của mình thì cả hộp chờ thành trò diễn.

Chuyện có thật hôm nay của tui. Tui lười mở terminal, gõ !ak secrets approve ... ngay trong Claude Code (dấu ! chạy lệnh shell trong session). Kết quả: bị từ chối, thông báo đại ý an agent may not answer its own request. Hợp lý thôi, vì lệnh ! chạy dưới tiến trình Claude, nên với vault nó y chang agent tự duyệt. Bài học: mở một tab terminal riêng (hoặc app desktop do bạn tự mở) rồi duyệt ở đó.

--help cũng tự nhận đây là "gờ giảm tốc", không phải ranh giới tuyệt đối: nó dựa vào việc nhận ra agent trong chuỗi tiến trình cha, và một tiến trình detach hoặc AGENTKIT_HOME bị đổi hướng có thể trông như terminal của bạn. Đừng coi nó là lá chắn duy nhất.

8.  4 Allow once vs allow 24h vs until revoked

Chuyện có thật thứ hai, cũng hôm nay: tui chọn allow once cho một job nhiều bước. Bước đầu chạy ngon, lần nhả duy nhất bị tiêu luôn, bước hai bị từ chối, job đứng giữa chừng. Đúng như --help ghi: once là "exactly once".

Chọn vầy cho đỡ khổ:

Việc Chọn
Một lệnh lẻ, key nhạy cảm (production, tiền) once
Job nhiều bước, chạy trong ngày, chạy xuyên đêm (/ak-atoz, /ak-orchestrate) ttl 24h (mặc định của CLI) hoặc --ttl vừa đủ
Key dev/test xài hằng ngày cho đúng một agent persist, nhưng nhớ revoke khi hết dùng
Không chắc deny, để nó hỏi lại

Một lưu ý: nếu vault đồng bộ có policy đòi duyệt mới, thì nó chỉ chấp nhận allow once, dùng trong vòng 10 phút.

8.  5 Grant gắn với 4 thứ, và với binary

Một grant gắn với bốn thứ

Một grant khớp khi đủ 4 trường: secret, project, fingerprint của binary agent, purpose. Purpose rỗng là một giá trị cụ thể, không phải wildcard. Hai git worktree của cùng repo là hai project, grant không mang qua lại. Update agent là đổi hash, phải trust --refresh. Một block luôn thắng mọi allow trên cùng scope.

Và --help của grant nói thẳng: cấp grant là tin model của agent đó với plaintext, vì model có thể tự chạy binary resolve. Chỉ cấp cái agent đó nên cầm.

8.  6 Exec scope không giới hạn được chương trình làm gì

Exec scope và phạm vi ảnh hưởng

Khi duyệt exec scope, cả CLI lẫn desktop đều cảnh báo:

  • Argument không nằm trong scope. Chương trình được bảo chạy gì trên dòng lệnh thì cái đó cũng nhận được giá trị.

  • Interpreter như node, python3 thì scope phủ mọi script nó được bảo chạy. Cảnh báo này được đưa lên đầu.

  • curl, wget, gh có thể được argument bảo gửi biến đi bất cứ đâu.

  • Tiến trình cùng user đọc được biến môi trường của chương trình lúc nó chạy.

  • Gạch bỏ output là best effort: giá trị bị encode, cắt nhỏ thì không nhận ra.

Nguyên văn lời khuyên của --help: chỉ cấp exec scope cho chương trình mà bạn sẵn sàng tự tay đưa giá trị cho nó. Duyệt node cho một key là duyệt cho mọi script node chạy, nên hãy chọn CLI chuyên dụng (stripe, gh) thay vì interpreter khi có thể.

8.  7 Lệnh nào agent không được chạy

Theo --help: approve, grant, devices approve, devices add --offer, sync enable --accept-sealed, sync now --relay từ chối khi agent chạy. Riêng trust --refresh đòi terminal tương tác và xác nhận trực tiếp. Skill ak-vault được dặn đưa lệnh cho bạn, không tìm đường vòng. Nếu agent của bạn cố lách mấy lệnh này, đó là dấu hiệu nên dừng lại đọc lại prompt.


9/ Nên và không nên

Nên ✅

  • Import .env bằng --dry-run trước, rồi xoá file gốc.

  • Đặt tên ref tìm được: <PROJECT>_<NAME>, hoặc tên chuẩn của nhà cung cấp như CLOUDFLARE_API_TOKEN cho key dùng chung.

  • Gắn --environment, --provider, --rotate-ttl khi set.

  • Duyệt trong terminal hoặc app desktop do bạn tự mở.

  • Job nhiều bước thì ttl, lệnh lẻ nhạy cảm thì once.

  • Xem ak secrets audit mỗi tuần, nhất là --decision deny.

  • Sau sự cố: revoke --all rồi rotate ở nhà cung cấp.

  • Cất recovery key và mật khẩu vault ngoài máy.

Không nên ❌

  • Dán secret vào khung chat với agent, kể cả "chỉ để nó set giùm".

  • Chạy approve qua ! trong Claude Code hay nhờ agent chạy giùm (đằng nào cũng bị từ chối).

  • Cấp exec scope cho node, python3, bash khi có CLI chuyên dụng.

  • Chọn persist cho key production.

  • Đưa credential production vào sync, dashboard hay remote MCP khi còn 🧪.

  • Gõ ${secret:...} vào commit message hay heredoc: nó có thể được thế giá trị ở chỗ bạn không muốn.

  • Coi .claudeignore, .cursorignore hay dòng "đừng đọc .env" trong AGENTS.md là bảo mật.


10/ Gỡ rối

Triệu chứng Nguyên nhân Cách xử lý
Lệnh agent fail ngay lần đầu đụng secret Fail-closed, chưa có grant (exit 8) ak secrets approve trong terminal của bạn
approve báo agent đang chạy phía trên (exit 6) Bạn chạy từ trong session agent (!, tool Bash) Mở terminal riêng
Bước 1 ok, bước 2 bị từ chối Allow once đã bị tiêu Duyệt lại với --state ttl --ttl 24h
Mới update Claude/Codex, cái gì cũng bị từ chối Hash binary đổi ak secrets trust claude --refresh
Đổi worktree là phải duyệt lại Hai worktree là hai project Bình thường; hoặc duyệt lại theo project đó
Agent bị chặn khi hỏi liên tục (exit 9) Rate limit theo fingerprint, đang cool-down Chờ, rồi cấp grant hợp lý thay vì để nó hỏi mãi
secrets run từ chối chương trình Shell/launcher bị cấm, hoặc chương trình đổi hash Chạy CLI thật, không bọc qua shell; duyệt lại exec scope
Chương trình trong run không tìm thấy helper Môi trường bị dựng lại, PATH chỉ có thư mục hệ thống Gọi helper bằng đường dẫn đầy đủ
compare trả exit 2 Giá trị dưới 16 ký tự Bình thường, dùng hint để so
Grant có --allow-host từ chối lệnh Bash Lệnh Bash không có destination để kiểm (exit 6) Dùng WebFetch.url, hoặc grant không giới hạn host
Trên Codex, lệnh có ${secret:...} bị từ chối Codex không có permission prompt cho hook Đọc mục AGENTKIT_SECRETS_INJECT_AUTO_ALLOW trong guide secrets trước khi bật
Sync báo integrity alarm (exit 13) Vault không qua kiểm chứng Dừng lại, đọc guide; không cố ép đồng bộ
Remote MCP trả no_device_online Không máy nào chạy relay ak secrets sync now --watch --relay trên một máy của bạn

Bất cứ lỗi nào: ak secrets <lệnh> --help có bảng exit status. Đọc nó trước khi đoán.


Tóm lại

1/ Rò rỉ secret tăng 34% năm 2025, secret AI tăng 81%, và agent đọc .env dù bị dặn. Plaintext trong tầm agent là đã lộ một nửa.

2/ Vault cục bộ ak secrets ✅: import .env, agent dùng ${secret:TEN}, thiếu grant là từ chối, bạn duyệt, mọi lần đọc có audit.

3/ Duyệt phải ở terminal hoặc app desktop do bạn tự mở. ! trong Claude Code tính là agent.

4/ once là đúng một lần. Job nhiều bước thì ttl. Desktop mặc định 1 giờ, CLI mặc định 24 giờ.

5/ Exec scope không giới hạn argument; node/python3 là phủ mọi script.

6/ Sync, dashboard, remote MCP còn 🧪. Thử với key dev/test, cất recovery key ngoài máy.


Bài trước: Personal kit và /ak-dogfood ←

Nguồn

Từ AgentKit (đọc 04/11/2026):

  • ak secrets --help, và --help của approve, request, grant, grants, revoke, audit, trust, run, set, get, list, import-env, compare, alias, sync, sync enable, sync now, sync status, devices, devices add, devices approve, ak gui (ak 3.0.0, HOME tạm).

  • Guide secrets: agentkit/docs/guides/secrets.md; thông báo lỗi an agent may not answer its own request: apps/cli/internal/commands/secretscmd/approve.go.

  • Dialog duyệt desktop: packages/ui/src/components/secrets/approval-modal.tsx, packages/ui/src/i18n/catalogs/en/secrets.ts; tài liệu agentkit-docs/content/docs/beta/desktop-app/secrets.en.mdx.

  • Skill ak-vault v1.0.0 (SKILL.md).

  • Repo ak-vault (MIT): https://github.com/bestagentkits/ak-vault (README, ADR 0001, ADR 0002, release gates).

  • https://vault.agentkit.best/guide/ và https://vault.agentkit.best/faq/

Bằng chứng bên ngoài:

Tìm hiểu sâu hơn trong tài liệu

Trang tham chiếu cho từng lệnh, skill, hook và thiết lập nhắc đến trong bài.

Đọc tài liệu →

Chia sẻ bài viết