Hướng dẫn, phê duyệt và cấu hình

Đưa cho trình trợ lý các tùy chọn viết rõ ràng và chọn cách nó xử lý thay đổi. Phần Instructions mô tả công việc bạn muốn; các kiểm soát phê duyệt quyết định hành động công cụ nào có thể tiến hành.

Settings → AI Assistant → Instructions. Đặt mô hình mặc định, viết hướng dẫn của bạn, rồi dùng Save instructions. Phần chụp trang PDF nằm dưới ô nhập văn bản. Mở ảnh chụp màn hình đầy đủ

Mô hình trò chuyện mặc định

Mở Settings → AI Assistant → Instructions. Chọn Default chat model để đặt mô hình dùng cho một cuộc trò chuyện mới. Danh sách chứa các mô hình đã bật từ những nhà cung cấp bạn đã cấu hình. Bạn vẫn có thể đổi mô hình trong từng cuộc trò chuyện riêng.

Hướng dẫn tùy chỉnh

Nhập tùy chọn của bạn vào Custom instructions, rồi bấm Save instructions. Một điểm khởi đầu hữu ích cho một bản thảo nghiên cứu là:

Ví dụ hướng dẫn viết

Use British English and preserve the terminology already used in the paper.
Keep citation keys, labels, equations, and numerical results unchanged unless
I explicitly ask you to edit them.
When a statement needs evidence, mark it for a source check. Do not invent
references or results.
Explain substantive changes briefly so I can review them.

Hãy viết các hướng dẫn này đủ cụ thể để dẫn dắt một lần chỉnh sửa mà không phải lặp lại cả đề cương dự án. Chúng bổ sung cho hành vi sẵn có của trình trợ lý và không thay đổi quyền công cụ của nó.

Lưu hướng dẫn

Bấm Save instructions sau khi chỉnh sửa. Chỉ báo Saved xác nhận đã được lưu. Một chỉnh sửa chưa lưu trong ô này không phải là mặc định mới của bạn.

Cho phép AI chụp trang PDF

Bật Allow PDF page capture for AI để trình trợ lý kiểm tra các trang đã kết xuất bằng một mô hình có hỗ trợ thị giác. Công cụ verify_pdf_pages quét hóa các trang đã biên dịch để kiểm tra bố cục. Tắt kiểm soát này khi bạn không muốn hình ảnh các trang được gửi đến nhà cung cấp đã cấu hình.

Xem danh mục công cụ

Mở rộng The assistant currently supports these tools trong tab Instructions. Dùng nó để xem những công việc trình trợ lý có thể thực hiện, rồi yêu cầu một kết quả chẳng hạn như biên dịch một mục, kiểm tra PDF, hoặc tìm một tham chiếu chưa được giải quyết.

Personas

Settings → AI Assistant → Personas. Nút Create persona nằm phía trên danh sách; các nút chỉnh sửa và xóa nằm cạnh mỗi persona. Mở ảnh chụp màn hình đầy đủ

Một persona là một bộ hướng dẫn đặt tên sẵn. Tạo một persona trong Settings → AI Assistant → Personas, rồi chọn nó trong ô soạn thảo trò chuyện cho một loại công việc nhất định. Ví dụ, giữ một persona soát lỗi ngắn gọn và một persona phản biện riêng.

Một persona đang bật sẽ cung cấp bộ hướng dẫn cho cuộc trò chuyện, thay cho văn bản hướng dẫn tùy chỉnh mặc định. Hãy đưa vào mọi tùy chọn thường trực mà persona đó cũng cần. Persona thay đổi phần hướng dẫn; nó không cấp quyền công cụ.

Chọn chế độ phê duyệt

Mở menu phê duyệt phía dưới ô nhập tin nhắn. Chế độ đang chọn hiển thị kèm dấu tích; chọn chính sách bạn muốn cho dự án của mình. Mở ảnh chụp màn hình đầy đủ

Dùng bộ chọn phê duyệt trong ô soạn thảo trò chuyện. Lựa chọn được lưu cho dự án hiện tại.

Chế độ	Hành vi
Ask for approval	Các công cụ phân loại đọc có thể chạy; các hành động khác phải hỏi trước
Approve for me	Công cụ đọc và công cụ mạng có thể chạy; thay đổi tệp và lệnh shell phải hỏi trước
Full access	Các hành động công cụ có thể chạy không cần nhắc phê duyệt, ngoại trừ công cụ bị quy tắc deny chặn
Custom	Các quy tắc allow và deny đã lưu được áp dụng, và công cụ không có quy tắc dùng chính sách rủi ro tiêu chuẩn

Approve for me là mặc định. Một số công cụ có kiểm tra riêng trong một thao tác. Biên dịch và kiểm tra PDF được đối xử khác với ghi một tệp nguồn hay thực thi một lệnh shell.

Phê duyệt một hành động đề xuất

Đọc tên công cụ và thao tác đề xuất trên thẻ phê duyệt. Phê duyệt để chạy hành động đó, hoặc từ chối để không áp dụng thay đổi đề xuất. Hãy tiếp tục cuộc trò chuyện với một yêu cầu hẹp hơn nếu hành động được đề nghị quá rộng.

Luôn dùng trong dự án này

Trong chế độ Custom, dùng Always in this project trên một lời nhắc phê duyệt để lưu quy tắc cho công cụ đó. Kiểm tra chế độ đang chọn khi bạn muốn một quy tắc ảnh hưởng đến lần chạy tiếp theo.

Xem lại hoặc xóa một quy tắc

Khi dự án đang mở, vào Settings → AI Assistant → Providers and keys và cuộn đến Tool approvals. Mỗi hàng hiển thị tên công cụ và việc nó luôn được cho phép hay luôn bị từ chối. Xóa một quy tắc để đưa công cụ đó trở lại chính sách rủi ro tiêu chuẩn trong chế độ Custom.

Chỉnh sửa approvals.toml

Approval rules file, phía dưới Tool approvals, dùng để chỉnh sửa ~/.oleafly/approvals.toml. Dùng Reload để đọc tệp hiện tại, Discard changes để bỏ các chỉnh sửa chưa lưu, hoặc Insert an example để bắt đầu từ một cấu hình mẫu. How the file works giải thích định dạng và hiển thị ID của dự án đang mở. Khi lưu, TOML được xác thực trước khi áp dụng, và các quy tắc có hiệu lực từ lần gọi công cụ tiếp theo.

Tệp có một bảng chế độ và các bảng quy tắc công cụ được khóa theo project folder ID, không phải tiêu đề hiển thị:

~/.oleafly/approvals.toml

["$approval_modes"]
"my-project-folder-id" = "custom"

["my-project-folder-id"]
write_file = "allow"
replace_in_file = "allow"
run_command = "deny"
delete_file = "deny"

Thay my-project-folder-id bằng ID thư mục thật của dự án. ID dự án là tên các thư mục dưới ~/.oleafly/projects. Giá trị chế độ là ask-for-approval, approve-for-me, full-access, và custom. Một dự án không được liệt kê dùng chế độ Approve for me. Giá trị quy tắc công cụ là allow và deny. Quy tắc deny áp dụng trong mọi chế độ, kể cả Full access, nên một công cụ bị từ chối sẽ không bao giờ chạy. Quy tắc allow chỉ áp dụng trong chế độ Custom. Công cụ không có quy tắc dùng chính sách rủi ro bình thường.

Các chú thích bắt đầu bằng # vẫn được giữ sau khi lưu từ Settings, nhưng chọn Always in this project trên một thẻ phê duyệt sẽ ghi lại tệp mà không còn chúng.

Dùng đúng tên công cụ từ danh mục. Các tên thường gặp gồm write_file, replace_in_file, create_file, rename_file, delete_file, run_command, compile, insert_figure, và set_main_doc.

Nên dùng tệp cấu hình nào?

Tệp	Mục đích
~/.oleafly/config.json	Cấu hình ứng dụng, quản lý qua Settings
~/.oleafly/approvals.toml	Chế độ phê duyệt dự án và quy tắc cho từng công cụ
~/.oleafly/agent.toml	Giới hạn và hướng dẫn đa tác nhân nâng cao
Cấu hình của tác nhân ngoài, chẳng hạn ~/.codex/config.toml	Thiết lập riêng và các kết nối MCP của tác nhân đó

Oleafly không dùng một tệp config.toml duy nhất cho mọi thiết lập này. Dùng giao diện Settings cho khóa nhà cung cấp và tùy chọn ứng dụng; thông tin đăng nhập được lưu mã hóa ở nơi riêng. Đừng thay toàn bộ cấu hình ứng dụng của bạn bằng một ví dụ ngắn.

Cấu hình agent.toml

Người dùng nâng cao có thể tạo ~/.oleafly/agent.toml để tinh chỉnh thiết lập đa tác nhân của trình trợ lý. Các thiết lập này điều khiển thời gian chạy tác nhân riêng của Oleafly, tách biệt với cấu hình của một tác nhân CLI đã kết nối.

~/.oleafly/agent.toml

maxAgentDepth = 2
maxConcurrentSubagents = 8
minWaitTimeoutMs = 1000
maxWaitTimeoutMs = 300000
defaultWaitTimeoutMs = 120000
waitAgentEnabled = true

usageHintText = """
Delegate independent checks with clear scopes. Keep writing decisions with
the parent agent, and close completed agents when their work is collected.
"""

subagentDeveloperInstructions = """
Work only on the assigned task. Report the files and evidence you inspected.
Do not spawn additional agents.
"""

maxAgentDepth

Giới hạn độ sâu lồng nhau. Mặc định là 2: các tác nhân con của một lần chạy không ủy quyền thêm nữa. Giá trị tối thiểu được chấp nhận là 1.

maxConcurrentSubagents

Giới hạn số tác nhân con chạy đồng thời trong một phiên. Mặc định là 8, và mức tối thiểu là 1. Nhiều tác nhân hơn có thể làm tăng mức dùng mô hình; chỉ nâng giới hạn cho công việc thực sự có thể chạy độc lập.

minWaitTimeoutMs

Đặt cận dưới cho thời gian chờ tác nhân, tính bằng mili-giây. Mặc định là 1000.

maxWaitTimeoutMs

Đặt cận trên cho thời gian chờ tác nhân. Mặc định là 300000, tức năm phút. Giá trị này luôn được giữ bằng hoặc cao hơn mức tối thiểu.

defaultWaitTimeoutMs

Đặt thời gian chờ mặc định. Mặc định là 120000, tức hai phút. Các giá trị bị giới hạn trong khoảng tối thiểu và tối đa đã cấu hình.

waitAgentEnabled

Điều khiển việc bật tính năng wait-agent. Mặc định là true.

usageHintText

Cung cấp hướng dẫn ủy quyền cho tác nhân cha. Ví dụ trên thay hướng dẫn mặc định bằng văn bản của riêng bạn.

subagentDeveloperInstructions

Cung cấp hướng dẫn cho các tác nhân con. Dùng nó để nêu phạm vi, kỳ vọng báo cáo, và việc có nên ủy quyền thêm hay không.

Thời gian chạy cũng chấp nhận các phiên bản snake_case của các khóa này, chẳng hạn max_agent_depth. Trường nào bị bỏ qua sẽ dùng mặc định. Tệp thiếu hoặc sai định dạng sẽ quay về mặc định, nên hãy kiểm tra cú pháp cẩn thận và bắt đầu một lần chạy mới sau khi đổi cấu hình.

Thử một quy tắc với một tác vụ nhỏ

1. Mở một dự án luyện tập và chọn Ask for approval.
2. Hỏi: “Hãy đọc tài liệu chính và đề xuất một tiêu đề rõ hơn. Hỏi trước khi thay đổi tệp.”
3. Xem xét thay đổi được đề xuất rồi phê duyệt hoặc từ chối nó.
4. Xem lại các quy tắc đã lưu trong Settings trước khi chuyển sang chế độ Custom.
5. Dùng Plan mode khi bạn muốn thống nhất vài bước trước khi bắt đầu chỉnh sửa.

Các trợ lý ngoài kết nối qua Oleafly MCP dùng chính sách của máy chủ MCP, được cấu hình riêng.