Khi AI agent như Claude Code hay Codex tự chạy SePay CLI, không có ai ngồi trước terminal để trả lời câu hỏi xác nhận. Agent phải tự biết mình đang ở sandbox hay production, lệnh nào phải để bạn tự chạy, và đọc kết quả ở đâu.
Trước khi giao terminal cho agent
Môi trường lấy từ --env; không có flag này thì theo default_env trong cấu hình, chưa đặt thì là sandbox. Kiểm tra active_env trong sepay --map=json trước khi chạy. Lệnh chỉ dành cho sandbox mà chạy với --env production thì dừng với exit code 2 (chi tiết khi default_env là production xem Lệnh chỉ chạy trên sandbox).
Mọi lệnh sửa dữ liệu trên production chỉ chạy khi bạn tự xác nhận trên terminal của mình. AI không tự xác nhận thay bạn: gặp lệnh này, AI đưa lệnh để bạn tự chạy.
Các lệnh này có confirms: terminal trong sepay --map=json --env production: webhook create, webhook update, webhook delete, webhook replay, bank-account update, paycode create, paycode update và sepay api với method khác GET, HEAD. Trên production, CLI chỉ chạy lệnh như vậy khi có --env production ngay trên lệnh, cộng một trong hai: có terminal để hỏi và người dùng trả lời y, hoặc lệnh nêu id tài nguyên kèm --yes. Thiếu thì CLI dừng với exit code 2, chưa gửi request nào. Không có terminal, câu báo có ask the user to run this command in their own terminal; có terminal, câu báo chỉ cách sửa lệnh (add --env production to the command…, run it without --yes, --json… and answer the prompt). Gặp câu nào trong số đó, agent cũng dừng và đưa lệnh cho bạn, không tự sửa lệnh theo câu báo. CLI không phân biệt agent với script: lệnh có --env production, id và --yes vẫn chạy, dù ai gõ. Vì vậy chốt chặn là agent không tự thêm --yes: gặp câu báo này, agent dừng lại, đưa nguyên lệnh (không có --yes) để bạn chạy trong terminal của mình và trả lời y. Bạn đồng ý trong khung chat cũng không phải lý do để agent thêm --yes. Luật đầy đủ ở Lệnh sửa dữ liệu trên production.
Trên sandbox (không có tiền thật), agent được tự thêm --yes cho lệnh hỏi xác nhận, như sandbox init --yes.
Scope chỉ bị kiểm tra trên production. Thiếu scope thì lệnh trả exit code 5: đăng nhập lại và cấp scope đó cùng các scope đang có (Xác thực).
Nên cho mỗi agent một bộ thông tin đăng nhập riêng: đặt SEPAY_CONFIG_DIR trỏ tới một thư mục profile riêng, hoặc chọn profile bằng --profile <tên>.
Thêm --json (hoặc -o yaml) để nhận kết quả dạng JSON trên stdout. Lỗi và cảnh báo đi ra stderr; exit code tra ở bảng exit code. Cách đọc cả ba trong script xem ở Script.
Quy tắc cho agent
Ghi các quy tắc này vào hướng dẫn của agent (ví dụ CLAUDE.md hoặc AGENTS.md):
- Luôn chạy với
--no-inputhoặc--json, để lệnh báo lỗi ngay thay vì chờ nhập. - Luôn truyền xid và mọi flag bắt buộc; không trông vào danh sách chọn trong terminal.
- Chạy lại một lệnh tạo dữ liệu thì dùng lại đúng
--idempotency-keycủa lần trước (Idempotency). - Không bao giờ tự thêm
--env productionhay--yescho lệnh sửa dữ liệu trên production, kể cả khi người dùng đã đồng ý trong khung chat. Đưa lệnh để người dùng tự chạy. Ngoại lệ:auth revoke --allvàlogout --allchỉ kết thúc phiên đăng nhập, nhận--yesở mọi môi trường; hỏi người dùng trước, đồng ý thì mới chạy với--yes. - Trước lệnh sửa dữ liệu trên production, chạy thử với
--dry-runvà cho người dùng xem kết quả (Chạy thử). - Gặp exit code 4, 5, 8, hoặc exit code 2 vì lệnh cần xác nhận, thì dừng và báo người dùng.
| Exit | Agent làm gì |
|---|---|
0 | Đọc kết quả trên stdout. |
1 | Đọc error_code. Chỉ thử lại khi bảng error code ghi Có, có giới hạn số lần; còn lại báo người dùng. |
2 | message có ask the user to run this command in their own terminal: dừng, đưa nguyên lệnh để người dùng tự chạy trong terminal của họ. message có targets production hoặc on production (needs confirmation, cannot confirm it): cũng dừng, đưa lệnh cho người dùng; không bỏ --json, không tự thêm --env production hay --yes. message có requires confirmation; pass --yes (gặp trên sandbox, và với auth revoke --all, logout --all ở mọi môi trường): hỏi người dùng, đồng ý thì chạy lại với --yes. Lỗi khác: sửa tham số theo --help. |
3 | Dừng, báo lệnh chưa được hỗ trợ. |
4 | Dừng, nhờ người dùng chạy sepay login. |
5 | Dừng, nhờ người dùng đăng nhập lại và cấp scope còn thiếu. |
6 | Báo handler không nhận thông báo; chạy lại sau khi handler được sửa. |
8 | Dừng; người dùng bật Test mode hoặc nhờ admin công ty cấp quyền. |
130 | Lệnh bị dừng giữa chừng (interrupted): người dùng bấm Ctrl+C hoặc Esc, hoặc tiến trình nhận SIGINT, SIGTERM. Không tự chạy lại; hỏi người dùng muốn làm gì tiếp. |
Ý nghĩa đầy đủ của từng exit code có ở Exit code và mã lỗi.
Một lượt chạy mẫu
Agent được nhờ xóa một webhook trên production. Trình tự hợp lý:
Agent xem môi trường đang dùng và profile đang đăng nhập:
$ sepay --map=json | jq '{active_env, authenticated, active_profile}'Agent kiểm tra phiên của profile đó còn dùng được:
$ sepay auth status --active --jsonAgent đọc ghi chú của lệnh trước khi chạy:
$ sepay webhook delete --helpAgent chạy thử để bạn thấy webhook nào sẽ bị xóa. Lệnh không gửi gì, chỉ đọc webhook đó:
$ sepay webhook delete <webhook-xid> --env production --dry-run --jsonAgent chạy lệnh thật. Không có terminal nên CLI dừng với exit code 2, chưa xóa gì:
$ sepay webhook delete <webhook-xid> --env production --json{"status": "error","error_code": "usage_error","message": "delete webhook on production needs confirmation; ask the user to run this command in their own terminal","exit_code": 2}Agent dừng và đưa lệnh cho bạn, không thêm --yes. Bạn tự chạy trong terminal của mình, xem lại xid rồi gõ y:
$ sepay webhook delete <webhook-xid> --env production! live: delete webhook <webhook-xid> targets PRODUCTIONenv: productiondelete webhook <webhook-xid> on production? [y/N] y✓ Deleted webhook <webhook-xid>.Xem lệnh nào làm gì: sepay --map=json
Lệnh này in toàn bộ cây lệnh kèm thông tin của từng lệnh, đủ để agent biết lệnh nào chỉ chạy trên sandbox, lệnh nào cần scope gì, lệnh nào xóa mà không lấy lại được. Ví dụ rút gọn:
{"name": "sepay","version": "x.x.x","active_env": "production","authenticated": true,"active_profile": "agent-claude","commands": [{"path": "sepay webhook delete","short": "Delete a webhook","aliases": ["rm", "del"],"args": "<webhook-xid>","implemented": true,"envs": "both","destructive": "irreversible","confirms": "terminal","scope": "webhook:write"}]}
| Trường | Mô tả |
|---|---|
active_env | Môi trường hiện tại (sandbox hoặc production). |
authenticated | Profile của lần chạy này (--profile, rồi SEPAY_PROFILE, rồi profile mặc định) đã đăng nhập hay chưa. |
active_profile | Profile mặc định trên máy: profile đăng nhập đầu tiên, hoặc profile chọn bằng sepay auth switch. Trường này không đổi theo --profile hay SEPAY_PROFILE; không có khi máy chưa có profile mặc định. |
commands | Mảng các đối tượng lệnh, xem Thông tin của mỗi lệnh. |
Thông tin của mỗi lệnh
| Thuộc tính | Kiểu | Ý nghĩa |
|---|---|---|
path | string | Lệnh đầy đủ, ví dụ sepay webhook delete. |
short | string | Mô tả một dòng bằng tiếng Anh. |
aliases | array | Tên viết tắt, như rm, del. |
args | string | Đối số vị trí. <webhook-xid>: có terminal thì CLI hỏi chọn khi bỏ trống, chạy không tương tác thì bắt buộc (thiếu là exit code 2). [webhook-xid]: tùy chọn, bỏ trống lệnh vẫn chạy. |
envs | string | sandbox nếu lệnh từ chối production, còn lại là both. |
scope | string | OAuth scope cần có trên production. |
destructive | string | irreversible nếu lệnh không hoàn tác được. |
confirms | string | Tính theo môi trường của lần chạy --map=json (active_env). terminal (chỉ có trên production): lệnh sửa dữ liệu production, chỉ chạy khi người dùng tự xác nhận (luật). always: hỏi cả trên sandbox, không có terminal thì cần --yes. conditional: một số cách gọi sẽ hỏi. Không có trường này: lệnh không hỏi. |
guidance | string | Ghi chú dễ đọc dành cho agent. |
flags | array | Định nghĩa flag (name, shorthand, type, desc, default, required). required: true là flag mà lần chạy không tương tác luôn phải truyền; flag chỉ bắt buộc khi đi kèm giá trị của flag khác thì ghi điều kiện trong desc. |
implemented | bool | false với lệnh chưa được hỗ trợ: lệnh bị ẩn khỏi --help và trả exit 3. |
Xem confirms của production bằng sepay --map=json --env production, của sandbox bằng --env sandbox. Ví dụ webhook delete là terminal trên production và always trên sandbox; sepay api là terminal trên production và conditional trên sandbox (chỉ -X DELETE hỏi). Lệnh không có destructive hoàn tác được nhưng vẫn có thể hỏi xác nhận, nên agent đọc cả hai trường trước khi chạy.
Xem thông tin của một lệnh trên production:
$ sepay --map=json --env production | jq '.commands[] | select(.path == "sepay webhook delete")'Liệt kê các lệnh agent không được tự chạy trên production:
$ sepay --map=json --env production | jq -r '.commands[] | select(.confirms == "terminal") | .path'Liệt kê các lệnh xóa mà không lấy lại được, để agent luôn hỏi bạn trước khi chạy:
$ sepay --map=json | jq -r '.commands[] | select(.destructive == "irreversible") | .path'Ghi chú cho agent trong --help
sepay <lệnh> --help có thêm khối Agent guidance, tóm tắt môi trường, trạng thái đăng nhập, scope, mức xác nhận và tính không hoàn tác của riêng lệnh đó. Khối của sepay webhook delete trên máy chưa đăng nhập:
[Agent guidance]Active env: sandbox (no real money).Not logged in: commands that read or write data exit 4 until you run `sepay login`.More: sepay help glossary | exit-codes | errors; sepay --map=paths lists every command.On production this needs the "webhook:write" scope: sepay auth refresh --scopes webhook:writeIrreversible: there is no command that undoes this. Confirm the target before running it.Prompts in sandbox too; there, without a terminal it exits 2 until you pass --yes.On production a write runs only with --env production on the command line (default_env does not count), and --yes confirms it only when the command names the resource it changes. Otherwise it exits 2: ask the user to run it in their own terminal. Do not add --env production or --yes to a write on the user's behalf.Writing a handler? The event body, the signature headers and what to return: https://developer.sepay.vn/en/sepay-webhooks/tich-hop-webhook.
Dòng Not logged in chỉ có khi máy chưa lưu phiên đăng nhập nào. Khối trong sepay --help thay dòng More: bằng danh sách đầy đủ hơn: sepay help glossary, sepay --map=paths và --map=json, sepay help exit-codes, sepay help errors, cùng link tới tài liệu này.
Dòng On production a write runs only… có ở mọi lệnh sửa dữ liệu production: agent không tự thêm --env production hay --yes, mà đưa lệnh để bạn tự chạy. Lệnh chỉ đọc thì không có dòng này.
Tra tài liệu ngay trong terminal
sepay help <chủ đề> in một chủ đề dạng Markdown ra stdout. Các chủ đề đi kèm bản CLI bạn cài, nên luôn đúng với phiên bản đang chạy:
| Chủ đề | Nội dung |
|---|---|
environment | Biến môi trường và tệp cấu hình CLI đọc |
errors | Từng error_code và cách xử lý |
exit-codes | Exit code và lúc nào nên thử lại |
glossary | Nghĩa của pg, bankhub, paycode, va, quota, xid |
Gõ sepay glossary cũng in chủ đề đó. Tên chủ đề sai thì lệnh dừng với exit code 2 và liệt kê các chủ đề có:
$ sepay help payloadError: unknown help topic "payload" (topics: environment, errors, exit-codes, glossary)Run 'sepay help --help' for usage.Quy định của nền tảng (trường trong payload, cách phản hồi, lịch gửi lại, chữ ký) nằm trên developer.sepay.vn. Thêm .md vào cuối URL để lấy bản Markdown của trang; llms.txt liệt kê mọi trang.
Xem thêm
Muốn Claude, ChatGPT hay Codex đọc dữ liệu SePay mà không cài CLI, kết nối SePay MCP.