Trang này được dịch từ tài liệu tiếng Anh. Lệnh, định danh và ví dụ giữ nguyên. Runtime 7.24.4 · SDK 2.6.7. Bản tiếng Anh

CLI không tương tác (ax-code run)

Trạng thái: Đang hoạt động Phạm vi: trạng thái hiện tại Xem xét lần cuối: 2026-09-22 Chủ sở hữu: người bảo trì môi trường chạy AX Code

ax-code run là điểm vào một lần, không tương tác, dành cho tác nhân lập trình AI và tập lệnh. Lệnh này gửi một lời nhắc duy nhất, in câu trả lời cuối của trợ lý, rồi thoát — không có giao diện terminal, không có lời nhắc tương tác. Hướng dẫn này trình bày bề mặt tùy chọn, hợp đồng đầu ra, mã thoát, và các công thức sao chép cho tập lệnh và CI.

Khởi chạy một lần chạy

Có bốn cách cung cấp lời nhắc. Chúng được ghép theo thứ tự: --prompt-file, rồi -p/--prompt, rồi thông điệp vị trí, rồi stdin được chuyển ống.

# Positional after -- (safest; flags after -- are never consumed as options)
ax-code run --model qwen -- "Review this change"

# Explicit prompt flag
ax-code run --model qwen --prompt "Review this change"
ax-code run --model qwen -p "Review this change"

# Prompt read from a file (not an attachment)
ax-code run --model qwen --prompt-file ./prompt.txt

# Piped stdin (used as the prompt when no positional/--prompt is given)
printf 'Review this change' | ax-code run --model qwen

Khi stdin không phải TTY, nội dung của nó được nối vào lời nhắc đã ghép, nên đó là toàn bộ lời nhắc khi không có gì khác được cung cấp. Bộ đọc stdin chờ một khoảng yên 300 ms trước khi bỏ một ống còn mở, nên hãy ghi lời nhắc kịp thời và đóng stdin — hoặc dùng --prompt-file cho lời nhắc lớn hoặc được tạo chậm. --prompt-file - đọc lời nhắc từ stdin một cách tường minh (lỗi cách dùng khi stdin là TTY); việc nối stdin chuyển ống ngầm không chạy lần thứ hai cho lần gọi đó.

-f/--file đính kèm tệp vào thông điệp và không bao giờ thay thế lời nhắc; tùy chọn này lặp lại được:

ax-code run --model qwen --file README.md --file src/main.ts -- "Summarize these"

Tệp đính kèm phải nằm trong thư mục dự án: máy chủ từ chối tệp đính kèm bên ngoài thư mục đó bất kể quy tắc quyền, nên CLI từ chối chúng ngay từ đầu bằng lỗi cách dùng. Hãy sao tệp vào dự án hoặc truyền nội dung bằng --prompt-file. --add-dir cấp cho công cụ quyền truy cập các thư mục bổ sung nhưng không đổi quy tắc này.

Kiểu mime của tệp đính kèm được suy từ phần mở rộng: png, jpg, jpeg, gif và webp ánh xạ tới kiểu image/* của chúng và pdf tới application/pdf, nên tệp đính kèm nhị phân tới máy chủ đúng kiểu thật thay vì text/plain. Mọi thứ khác — kể cả tệp không có phần mở rộng được nhận ra — được gửi dưới dạng text/plain, và thư mục đính kèm được phân loại application/x-directory.

Điều hướng lần chạy

Ba cờ điều hướng một lần chạy mà không đổi văn bản lời nhắc. Tất cả đều chỉ có dạng dài và kebab-case.

--append-system-prompt TEXT / --append-system-prompt-file PATH

Nối thêm văn bản vào lời nhắc hệ thống sau các lời nhắc hệ thống của tác nhân và môi trường — nó nối thêm và không bao giờ thay thế lời nhắc hệ thống dựng sẵn. Hai dạng loại trừ lẫn nhau. Biến thể tệp thuận tiện cho chỉ dẫn dài hơn; đúng một dòng mới ở cuối được cắt, và văn bản rỗng (hoặc tệp không đọc được) là lỗi cách dùng trước khi bất kỳ thứ gì được gửi.

ax-code run --model qwen --append-system-prompt "Answer in English only" -- "Review this change"

--disallowed-tools a,b

Tắt công cụ theo id cho lần chạy (phân tách bằng dấu phẩy, lặp lại được). Cờ được áp dụng qua cả hai cơ chế máy chủ: quy tắc từ chối trên phiên đã tạo bao phủ các lần chạy mới, và một bản đồ công cụ theo yêu cầu cũng bao phủ các lần chạy --session/--continue được tiếp tục. Từ chối bash cũng từ chối lệnh của công cụ monitor, vốn chạy qua cùng bộ khởi chạy shell; một lời gọi chạm quy tắc từ chối thất bại như lỗi công cụ và được tính là một lần từ chối cho trạng thái lần chạy bị chặn. Id không xác định không phải lỗi — id công cụ MCP là động — nhưng với định dạng mặc định, mỗi id ngoài tập công cụ dựng sẵn in một cảnh báo stderr (bị --quiet chặn).

ax-code run --model qwen --disallowed-tools bash,write -- "Audit this module without mutating anything"

--add-dir PATH

Cấp cho tác nhân quyền truy cập một thư mục bổ sung (lặp lại được): một quy tắc cho phép external_directory cho <resolved-path>/* được thêm vào quy tắc quyền của phiên mới, bao phủ thư mục đó và mọi thứ bên dưới. Mỗi đường dẫn phải tồn tại và là thư mục (được phân giải theo cwd của bên gọi giống --file). Quy tắc được áp dụng khi phiên được tạo, nên dưới --session/--continue nó không thể có hiệu lực — CLI in --add-dir applies only to new sessions trên stderr rồi tiếp tục. Nó không đổi sự bao hàm của --file: tệp đính kèm vẫn phải nằm trong thư mục dự án. Nó bao phủ các công cụ tệp (read, glob, grep, list, edit, write); một lệnh shell đi vào thư mục qua đường dẫn động vẫn kích hoạt lời nhắc truy cập đường dẫn chỉ dành cho tương tác, và lần chạy không tương tác tự từ chối lời nhắc đó, nên hãy ưu tiên công cụ tệp hoặc truyền nội dung tệp một cách tường minh.

ax-code run --model qwen --add-dir ../design-docs -- "Read ../design-docs/spec.md and summarize it"

Chọn mô hình

Liệt kê các ID dùng được bằng ax-code models. Truyền giá trị provider/model thu được cho --model (-m):

ax-code models            # one "provider/model" ID per line
ax-code models --json     # one JSON document

ax-code models --json in một tài liệu duy nhất có dạng {"models":[{"id":"provider/model","provider":"...","model":"...","connected":true}]}.

Các tên họ deepseek, glm và qwen phân giải về mặc định Flash của chúng, nên ax-code run --model qwen -- "..." hoạt động mà không cần viết đầy đủ ID provider/model. Bỏ qua --model sẽ dùng mặc định đã cấu hình; tác nhân và mô hình có hiệu lực được in ra stderr dưới dạng > Agent · model.

Định dạng đầu ra

--format nhận default (mặc định), json, jsonl hoặc ndjson (jsonl và ndjson là bí danh của json).

Mặc định (văn bản)

Định dạng mặc định chỉ in văn bản trợ lý cuối trên stdout. Mọi tiến trình, hoạt động công cụ và chẩn đoán đi tới stderr, bắt đầu bằng tiêu đề > Agent · model · ses_... gồm id phiên, nên bên gọi nhiều lượt có thể tiếp tục bằng --session mà không chuyển sang --format json (--quiet chặn tiêu đề). Màu ANSI bị tắt khi stderr không phải TTY hoặc khi NO_COLOR được đặt (bất kỳ giá trị nào), nên lần chạy chuyển ống không bao giờ phát mã thoát ANSI.

Luồng JSON (--format json)

--format json in một luồng sự kiện JSON phân tách bằng dòng mới (NDJSON) — một đối tượng JSON mỗi dòng, không phải một tài liệu JSON duy nhất. Sự kiện gồm step_start, text, tool_use, reasoning (chỉ khi có --thinking), permission_denied, error và step_finish. Luồng luôn kết thúc bằng đúng một dòng result:

{
  "type": "result",
  "timestamp": 1727000000000,
  "sessionID": "ses_...",
  "status": "completed",
  "text": "...",
  "permissionDenials": 0,
  "usage": { "input": 1200, "output": 80, "reasoning": 0, "cacheRead": 0, "cacheWrite": 0 }
}

status là completed, blocked hoặc error. usage chỉ mang số token — input, output, reasoning, cacheRead, cacheWrite — và bị bỏ hoàn toàn khi các số đó không xác định; không có trường chi phí. Khi một lần chạy thất bại trước khi gửi (cờ sai, mô hình không xác định, v.v.), định dạng luồng in một dòng trước khi thoát:

{ "type": "error", "error": { "code": "usage", "message": "..." } }

error.code là một trong các mã sau:

Mã thoát

Hộp cát

--sandbox read-only|workspace-write|full-access chọn chế độ cô lập (mặc định full-access). Trong các lần chạy không tương tác, các yêu cầu quyền bị tự từ chối và được báo dưới dạng sự kiện permission_denied, nên một lần chạy cần ghi những gì nó không được phép sẽ báo blocked và thoát 3. Điều này cũng bao phủ tác nhân con: các yêu cầu phát sinh trong phiên con do công cụ task tạo bị từ chối theo cùng cách, và sự kiện permission_denied của chúng mang sessionID của phiên con. Các lời gọi công cụ bị quy tắc từ chối quyền chặn (ví dụ từ --disallowed-tools) hoặc bị hộp cát chỉ đọc cũng được tính là lần từ chối. Các công cụ tương tác question và plan_exit luôn bị tắt trong lần chạy không tương tác, kể cả trên phiên được tiếp tục. Chỉ dùng read-only khi không kỳ vọng đột biến; workspace-write giữ các lần ghi bên trong dự án.

Dưới --attach, cờ cũng được gửi như chính sách cô lập theo từng yêu cầu trong mọi thân lời nhắc; máy chủ áp dụng chế độ chặt hơn giữa chế độ của chính nó và chính sách được yêu cầu, nên chỉ có thể siết chặt hơn. Cùng chính sách theo yêu cầu được gửi cho các máy chủ thuộc sở hữu cục bộ, giữ hành vi thống nhất.

Đầu ra có cấu trúc

-o/--output-file <path> ghi văn bản trợ lý cuối vào một tệp. --output-schema <file> xác thực văn bản cuối dưới dạng JSON đối chiếu một tệp JSON Schema; chỗ không khớp được báo là sự kiện error với result.status error và thoát

1. Tệp lược đồ được kiểm tra trước khi mô hình chạy — một lược đồ không đọc được, không phân tích được, hoặc không phải đối tượng là lỗi cách dùng trước khi bất kỳ thứ gì được gửi. Khi thành công, lược đồ đã phân tích cũng được gửi tới mô hình như định dạng đầu ra json_schema của lần chạy, và máy chủ thử lại câu trả lời không hợp lệ tới hai lần trước khi bước xác thực cuối của chính CLI chạy như chốt chặn. Đầu ra cuối là đối tượng có cấu trúc đã tuần tự hóa (một dòng JSON): đó là nội dung mà stdout, --output-file và result.text mang:

ax-code run --model qwen --output-schema ./answer.schema.json -- "Return a JSON object with a summary field"

Phiên và việc tiếp tục

• -c/--continue — tiếp tục phiên gần nhất.
• -s/--session <id> — tiếp tục một phiên cụ thể theo ID.
• --fork — rẽ nhánh phiên trước khi tiếp tục (cần --continue hoặc --session).
• --show-history — in lịch sử phiên nhìn thấy được khi tiếp tục (cần --continue hoặc --session).
• --attach <url> — gắn vào máy chủ đang chạy sẵn thay vì khởi động máy chủ mới; kết hợp với --dir để nhắm thư mục dự án trên máy chủ đó. Máy chủ được bảo vệ bằng AX_CODE_SERVER_PASSWORD nhận --password (hoặc cùng biến ở phía bên gọi); môi trường chạy được quản lý lấy token từ AX_CODE_RUNTIME_TOKEN.
• --runtime — gắn vào môi trường chạy được quản lý của thư mục dự án (--dir hoặc cwd của bên gọi) đã khởi động bằng ax-code runtime start, phân giải URL và token từ bản ghi môi trường chạy riêng. Khi không có môi trường chạy nào đang chạy, lần chạy thất bại trước mọi yêu cầu với mã lỗi attach và một thông điệp nêu lệnh khởi động. --runtime và --attach loại trừ lẫn nhau.

Công thức

Một lần

ax-code run --model qwen -- "Fix the failing test in src/parser.ts"

Giới hạn lần chạy bằng thời gian chờ

ax-code run --timeout 120 --model qwen -- "Fix the failing test in src/parser.ts"

--timeout <seconds> hủy lần chạy trên máy chủ và thoát 124 (result.status là timeout) khi lần chạy vượt giới hạn, nên một tác nhân bị kẹt không thể giữ một việc CI mở vô thời hạn. Giới hạn bao phủ toàn bộ lần gọi — nó được kích hoạt trước lời gọi máy chủ đầu tiên, nên ngay cả máy chủ --attach bị nuốt hoặc khởi động treo cũng kết thúc đúng hạn (trong trường hợp sớm đó, dòng kết quả mang sessionID rỗng).

Chờ tác nhân con chạy nền

ax-code run --await-background 300 --timeout 360 --model qwen -- \
  "Delegate the independent checks, then integrate their results"

--await-background <seconds> giữ lần gọi này mở cho các tiến trình con task chạy nền do phiên của nó tạo và các lượt theo dõi của tiến trình cha được kích hoạt bởi kết quả của chúng. Tùy chọn này phải được bật rõ và bị giới hạn 3600 giây. Câu trả lời cuối và result.text JSON đến từ lượt cha hoàn tất cuối cùng. Nếu các tiến trình con hoặc phần theo dõi của chúng không ổn định trong giới hạn chờ, lần chạy báo lỗi và thoát 1. --timeout vẫn là giới hạn tổng thể. Các tác vụ dự án đã lên lịch chạy trong các phiên riêng và không thuộc khoảng chờ này. Lệnh một lần này không nhận các lịch dự án đến hạn; một backend bền vững sở hữu việc điều phối của chúng.

Phân tích luồng JSON

result=$(ax-code run --format json --model qwen -- "..." | tail -n 1)
echo "$result" | jq -r '.status'
echo "$result" | jq -r '.text'

Dòng result luôn là dòng cuối, nên tail -n 1 tách được nó ngay cả khi luồng kết thúc sớm.

Rà soát chỉ đọc

ax-code run --sandbox read-only --model qwen -- "Review this diff for bugs"

Đầu ra JSON có cấu trúc kèm lược đồ

cat > answer.schema.json <<'JSON'
{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}
JSON
ax-code run --model qwen --output-schema answer.schema.json --output-file answer.json \
  -- "Return JSON with a one-sentence summary"

Tiếp tục một phiên

# Start a session and note the sessionID from the result line
ax-code run --format json --model qwen -- "Draft the outline" | tail -n 1

# Continue it
ax-code run --model qwen --session ses_... -- "Now write section 2"

Đính kèm một tệp

ax-code run --model qwen --file docs/spec.md -- "Summarize the attached spec"

Lệnh máy đọc được

ax-code run --format json phát một luồng sự kiện phân tách bằng dòng mới (xem luồng JSON); đây là bề mặt --json duy nhất có phát luồng. Mọi lệnh chỉ đọc khác mang cờ --json tuân theo một hợp đồng chặt hơn: khi thành công nó ghi đúng một tài liệu JSON ra stdout, và khi thất bại stdout vẫn trống trong khi một tài liệu {"error":{"code","message"}} duy nhất đi tới stderr và mã thoát là 1.

Các lệnh có --json:

• ax-code session list --json
• ax-code models --json
• ax-code providers list --json
• ax-code agent list --json
• ax-code mcp list --json
• ax-code mcp auth list --json
• ax-code stats --json
• ax-code context --json
• ax-code memory status --json
• ax-code memory list --json
• ax-code task list --json / ax-code task show <taskID> --json
• ax-code schedule list --json / ax-code schedule show <taskID> --json
• ax-code runtime list --json / ax-code runtime status --json
• ax-code doctor --json
• ax-code risk <sessionID> --json
• ax-code wiki status --json
• ax-code workflow list --json / ax-code workflow status <runID> --json

ax-code runtime status in tài liệu JSON của nó vô điều kiện — cờ --json được chấp nhận cho nhất quán nhưng hành động trạng thái luôn phát JSON trên stdout.

Gọi ax-code từ một tác nhân khác

Khi bọc ax-code run từ một tập lệnh, bước CI, hoặc một tác nhân khác:

• Dùng --format json và đọc dòng cuối — bản ghi result luôn là dòng cuối, kể cả khi luồng kết thúc sớm.
• Lấy sessionID từ dòng kết quả đó cho mọi lượt theo dõi; truyền lại bằng --session.
• Đừng dùng --continue từ các bên gọi đồng thời — nó tiếp tục phiên gần nhất, vốn tranh chấp khi nhiều bên gọi cùng hoạt động; hãy truyền một id --session tường minh.
• Truyền một --model tường minh để lần chạy không phụ thuộc mặc định đã cấu hình có thể đổi.
• Luôn truyền --timeout để một tác nhân bị kẹt không thể giữ bên gọi mở.
• Đóng stdin, hoặc dùng --prompt-file / --prompt-file -: bộ đọc ống ngầm bỏ cuộc sau một khoảng yên 300 ms và cắt cụt một ống chậm một cách âm thầm.
• Đặt NO_COLOR=1, hoặc dựa vào phát hiện không phải TTY, để lần chạy chuyển ống không bao giờ phát mã thoát ANSI.
• Chạy từ thư mục dự án: thư mục nhà hoặc thư mục cha nhiều kho bị từ chối ở chế độ không tương tác. Đặt AX_CODE_ALLOW_BROAD_DIR=1 để ghi đè chốt đó.
• Lỗi cách dùng không in gì trên stdout (trợ giúp và lỗi một dòng đi tới stderr), nên một lệnh gõ sai để stdout trống với mã thoát 1. Dưới --format json, lỗi cách dùng cũng được ghi thành một dòng error trên stdout.
• Một tín hiệu đến khi tiến trình vẫn đang tải, trước khi lệnh run hoạt động, kết thúc tiến trình với mã thoát 130 và không có đầu ra; khi lệnh đã hoạt động, SIGINT và SIGTERM luôn tạo đúng một dòng kết thúc result với trạng thái cancelled.