Tham chiếu bộ khung Codex

Tài liệu tham khảo này trình bày cấu hình chi tiết cho plugin codex chính thức. Để thiết lập và đưa ra quyết định định tuyến, hãy bắt đầu với bộ điều phối Codex.

Bề mặt cấu hình Plugin

Tất cả cài đặt của bộ điều phối Codex nằm trong plugins.entries.codex.config.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },          appServer: {            mode: "guardian",          },        },      },    },  },}

Các trường cấp cao nhất:

Giám sát

Tính năng giám sát liệt kê các phiên Codex chưa lưu trữ từ máy tính Gateway và các Node đã ghép cặp có chủ động chọn tham gia. Hãy bật tính năng này độc lập với bộ điều phối tác tử:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          supervision: {            enabled: true,          },        },      },    },  },}

Các trường supervision:

Các mục điểm cuối chấp nhận những trường sau:

Trang Codex Sessions sử dụng App Server giám sát của plugin và chỉ hiển thị các phiên chưa lưu trữ. Khi không có cài đặt kết nối appServer rõ ràng, kết nối đó là stdio thư mục chính của người dùng được quản lý. Các hàng cục bộ đã lưu hoặc đang rảnh có thể tạo một Chat bị khóa theo mô hình với lịch sử người dùng và trợ lý có giới hạn, kéo dài đến lượt nguồn đã lưu bền vững gần nhất ở trạng thái kết thúc. Liên kết riêng tư của Chat duy trì nhánh ảnh chụp nhanh, nhánh nguồn appServer chuẩn, việc chèn lịch sử và các lượt sau đó trên kết nối ấy. Lần khởi động chuẩn đầu tiên sử dụng cặp được trả về từ thao tác phân nhánh. Các lần tiếp tục sau bỏ qua phần ghi đè mô hình và nhà cung cấp của OpenClaw để Codex khôi phục cặp đã lưu bền vững của luồng chuẩn; một thay đổi gốc riêng biệt có thể cập nhật cặp đó, nhưng mô hình bên ngoài và chuỗi dự phòng không bao giờ thay thế nó. Các hàng đã lưu và đang rảnh có thể được lưu trữ sau khi xác nhận không có trình chạy nào khác, trừ khi một liên kết OpenClaw đang hoạt động khác sở hữu chính xác đích đó hoặc một trong các phiên con chưa lưu trữ được tạo ra từ đích ấy. OpenClaw tuân theo cơ chế phân trang phiên con của Codex và đóng an toàn khi xảy ra lỗi liệt kê, chu trình hoặc cạn giới hạn an toàn. Việc xác nhận vẫn bao quát các máy khách gốc không xác định và tình trạng tranh chấp giữa trạng thái với thao tác lưu trữ. Không thể xóa Chat bị khóa theo mô hình có giám sát khi nó đang bảo vệ liên kết gốc. Nguồn đang hoạt động không thể tạo nhánh hoặc được lưu trữ, nhưng vẫn có thể mở một Chat có giám sát hiện có. Mọi hàng của Node đã ghép cặp đều giữ trạng thái chỉ đọc; phương thức truyền tải của Node chưa cung cấp vòng đời truyền trực tuyến mà bộ điều phối cần.

Chỉ riêng appServer.homeScope: "user" thay đổi thư mục chính Codex mà tiến trình bộ điều phối được quản lý sử dụng; nó không công bố danh mục toàn hệ thống. Việc bật giám sát không thay đổi giá trị mặc định của bộ điều phối. Thay vào đó, kết nối giám sát riêng mặc định sử dụng stdio thư mục chính của người dùng được quản lý khi không có cài đặt kết nối appServer rõ ràng. Các cài đặt rõ ràng được tuân thủ cho kết nối đó. Các liên kết có giám sát đang chờ và đã xác nhận duy trì kết nối ấy trong mọi lượt; nếu giám sát bị tắt hoặc kết nối/vòng đời sai lệch, hệ thống sẽ đóng an toàn thay vì quay về bộ điều phối dùng thư mục chính của tác tử. Kết nối mặc định chia sẻ các phiên đã lưu với máy khách Codex gốc, không chia sẻ trạng thái hoạt động cục bộ theo tiến trình của chúng.

Các cài đặt plugins.entries.codex-supervisor cũ đã ngừng sử dụng. Chạy openclaw doctor --fix để di chuyển mục cũ, các định nghĩa điểm cuối, cờ chính sách và tham chiếu danh sách cho phép/từ chối Plugin vào khối này. Các giá trị chuẩn codex.config.supervision được khai báo rõ ràng sẽ được ưu tiên khi có xung đột.

Phương thức truyền tải máy chủ ứng dụng

Đối với các lượt bộ điều phối thông thường, OpenClaw khởi động tệp nhị phân Codex được quản lý đi kèm Plugin chính thức (hiện là @openai/codex 0.144.1):

codex app-server --listen stdio://

Cách này giữ phiên bản máy chủ ứng dụng gắn với Plugin codex chính thức, thay vì phụ thuộc vào bất kỳ Codex CLI riêng biệt nào tình cờ được cài đặt cục bộ. Chỉ đặt appServer.command khi bạn chủ ý muốn dùng một tệp thực thi khác. Các lượt được quản lý thông thường với thư mục chính tác tử cô lập mặc định ưu tiên gói đã ghim này ngay cả khi đã cài đặt gói ứng dụng máy tính macOS. Khi Computer Use được bật, hoặc khi homeScope là "user" và có thể tải trạng thái Computer Use gốc, quá trình khởi động được quản lý thay vào đó ưu tiên tệp nhị phân của ứng dụng máy tính sở hữu các quyền macOS cần thiết. Quy tắc ưu tiên ứng dụng máy tính tương tự cũng áp dụng khi cấu hình Codex hiệu dụng của thư mục chính tác tử cô lập bật Computer Use gốc. Nếu không cài đặt gói ứng dụng máy tính, OpenClaw quay về tệp nhị phân của gói đã ghim.

Việc bàn giao tệp thực thi và cô lập cấu hình gốc phối hợp các máy khách bên trong một tiến trình Gateway đang chạy. Hãy khởi động lại Gateway sau khi một tiến trình khác thay đổi cấu hình Plugin Codex gốc.

Tính năng giám sát phân giải một kết nối riêng. Khi không có cài đặt kết nối appServer rõ ràng, nó sử dụng stdio được quản lý với homeScope: "user"; bộ điều phối thông thường vẫn sử dụng stdio được quản lý với homeScope: "agent". Các cài đặt kết nối rõ ràng được cả hai đường dẫn tuân thủ. Đặt rõ ràng homeScope: "user" khi bộ điều phối thông thường cần chia sẻ $CODEX_HOME (hoặc ~/.codex) với các máy khách gốc. Một liên kết riêng tư có giám sát sử dụng kết nối giám sát bất kể giá trị mặc định của bộ điều phối thông thường. Các tiến trình App Server độc lập duy trì trạng thái hoạt động và trạng thái phê duyệt riêng biệt.

Đối với máy chủ ứng dụng đang chạy sẵn, hãy sử dụng phương thức truyền tải WebSocket:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            transport: "websocket",            url: "ws://gateway-host:39175",            authToken: "${CODEX_APP_SERVER_TOKEN}",            requestTimeoutMs: 60000,          },        },      },    },  },}

Các trường appServer:

appServer.networkProxy được chỉ định rõ vì nó thay đổi hợp đồng sandbox của Codex. Khi được bật, OpenClaw cũng đặt features.network_proxy.enabled và default_permissions trong cấu hình luồng Codex để hồ sơ quyền được tạo có thể khởi động mạng do Codex quản lý. Theo mặc định, OpenClaw tạo tên hồ sơ openclaw-network-<fingerprint> có khả năng chống xung đột từ nội dung hồ sơ; chỉ dùng profileName khi cần một tên cục bộ ổn định.

export default {  plugins: {    entries: {      codex: {        config: {          appServer: {            sandbox: "workspace-write",            networkProxy: {              enabled: true,              domains: {                "api.openai.com": "allow",                "blocked.example.com": "deny",              },              allowUpstreamProxy: true,              proxyUrl: "http://127.0.0.1:3128",            },          },        },      },    },  },};

Nếu runtime app-server thông thường sẽ là danger-full-access, việc bật networkProxy sẽ sử dụng quyền truy cập hệ thống tệp kiểu không gian làm việc cho hồ sơ quyền được tạo thay thế. Việc thực thi mạng do Codex quản lý là kết nối mạng trong sandbox, vì vậy hồ sơ toàn quyền truy cập sẽ không bảo vệ lưu lượng đi.

Plugin chặn các phiên bắt tay app-server cũ hơn hoặc không có phiên bản: app-server Codex phải báo cáo phiên bản ổn định 0.143.0 trở lên.

OpenClaw coi các URL app-server WebSocket không phải loopback là từ xa và yêu cầu xác thực WebSocket mang danh tính thông qua appServer.authToken hoặc header Authorization. appServer.authToken và mỗi giá trị appServer.headers.* có thể là SecretInput; runtime bí mật phân giải SecretRefs và dạng viết tắt env trước khi OpenClaw tạo các tùy chọn khởi động app-server, còn SecretRefs có cấu trúc chưa được phân giải sẽ gây lỗi trước khi bất kỳ token hoặc header nào được gửi. Khi các plugin Codex gốc được cấu hình, OpenClaw sử dụng mặt phẳng điều khiển plugin của app-server đã kết nối để cài đặt hoặc làm mới các plugin đó, rồi làm mới danh mục ứng dụng để các ứng dụng do plugin sở hữu hiển thị với luồng Codex. app/list vẫn là nguồn danh mục và siêu dữ liệu có thẩm quyền, nhưng chính sách OpenClaw quyết định liệu thread/start có gửi config.apps[appId].enabled = true cho một ứng dụng được liệt kê và có thể truy cập hay không, ngay cả khi Codex hiện đánh dấu ứng dụng đó là đã tắt. Các id ứng dụng không xác định hoặc bị thiếu vẫn bị từ chối theo nguyên tắc đóng; đường dẫn này chỉ kích hoạt các plugin từ marketplace thông qua plugin/install và làm mới danh mục. Chỉ kết nối OpenClaw với các app-server từ xa được tin cậy để chấp nhận việc cài đặt plugin và làm mới danh mục ứng dụng do OpenClaw quản lý.

Chế độ phê duyệt và sandbox

Các phiên app-server stdio cục bộ mặc định dùng chế độ YOLO: approvalPolicy: "never", approvalsReviewer: "user" và sandbox: "danger-full-access". Tư thế vận hành cục bộ đáng tin cậy này cho phép các lượt chạy và Heartbeat OpenClaw không có người giám sát tiếp tục tiến triển mà không xuất hiện lời nhắc phê duyệt gốc khi không có ai ở đó để phản hồi.

Nếu tệp yêu cầu hệ thống cục bộ của Codex không cho phép ngầm định các giá trị phê duyệt, người xét duyệt hoặc sandbox của YOLO, OpenClaw sẽ coi giá trị mặc định ngầm định là guardian và chọn các quyền guardian được phép. tools.exec.mode: "auto" cũng buộc các phê duyệt Codex phải được guardian xét duyệt và không giữ lại các ghi đè cũ không an toàn approvalPolicy: "never" hoặc sandbox: "danger-full-access"; đặt tools.exec.mode: "full" để chủ ý sử dụng tư thế không cần phê duyệt. Các mục [[remote_sandbox_config]] khớp tên máy chủ trong cùng tệp yêu cầu được áp dụng khi quyết định giá trị sandbox mặc định.

Đặt appServer.mode: "guardian" để các phê duyệt Codex được guardian xét duyệt:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            mode: "guardian",            serviceTier: "priority",          },        },      },    },  },}

Giá trị đặt sẵn guardian được mở rộng thành approvalPolicy: "on-request", approvalsReviewer: "auto_review" và sandbox: "workspace-write" khi các giá trị đó được phép. Các trường chính sách riêng lẻ sẽ ghi đè mode. Giá trị người xét duyệt cũ guardian_subagent vẫn được chấp nhận làm bí danh tương thích, nhưng cấu hình mới nên sử dụng auto_review.

Khi sandbox OpenClaw đang hoạt động, tiến trình app-server Codex cục bộ vẫn chạy trên máy chủ Gateway. Vì vậy, OpenClaw vô hiệu hóa Code Mode gốc của Codex, các máy chủ MCP của người dùng và việc thực thi plugin dựa trên ứng dụng trong lượt đó thay vì coi sandbox phía máy chủ Codex là tương đương với backend sandbox của OpenClaw. Quyền truy cập shell được cung cấp thông qua các công cụ động dựa trên sandbox của OpenClaw như sandbox_exec và sandbox_process khi các công cụ exec/process thông thường khả dụng.

Thực thi gốc trong sandbox

Giá trị mặc định ổn định là từ chối theo nguyên tắc đóng: sandbox OpenClaw đang hoạt động sẽ vô hiệu hóa các bề mặt thực thi Codex gốc vốn sẽ chạy từ máy chủ app-server Codex. Chỉ sử dụng appServer.experimental.sandboxExecServer: true khi bạn muốn thử khả năng hỗ trợ môi trường từ xa của Codex với backend sandbox của OpenClaw. Đường dẫn xem trước này hoạt động với mọi phiên bản app-server Codex được hỗ trợ.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            experimental: {              sandboxExecServer: true,            },          },        },      },    },  },}

Khi cờ này được bật và phiên OpenClaw hiện tại nằm trong sandbox, OpenClaw khởi động một exec-server local loopback được backend sandbox đang hoạt động hỗ trợ, đăng ký nó với app-server Codex, rồi khởi động luồng và lượt Codex với môi trường do OpenClaw sở hữu đó. Nếu app-server không thể đăng ký môi trường, lượt chạy sẽ thất bại theo nguyên tắc đóng thay vì âm thầm chuyển về thực thi trên máy chủ.

Đường dẫn xem trước này chỉ dành cho môi trường cục bộ. Một app-server WebSocket từ xa không thể truy cập exec-server loopback trừ khi nó chạy trên cùng máy chủ, vì vậy OpenClaw từ chối tổ hợp đó.

Xác thực và cô lập môi trường

Trong thư mục chính mặc định của từng tác tử, phương thức xác thực được chọn theo thứ tự sau:

1. Một hồ sơ xác thực OpenClaw Codex được chỉ định rõ ràng cho tác tử.
2. Tài khoản hiện có của app-server trong thư mục chính Codex của tác tử đó.
3. Chỉ đối với các lần khởi chạy app-server stdio cục bộ, CODEX_API_KEY, rồi OPENAI_API_KEY, khi không có tài khoản app-server và vẫn cần xác thực OpenAI.

Khi OpenClaw phát hiện hồ sơ xác thực Codex kiểu gói đăng ký ChatGPT (loại thông tin xác thực OAuth hoặc token), nó xóa CODEX_API_KEY và OPENAI_API_KEY khỏi tiến trình con Codex được tạo. Việc này giữ cho các khóa API cấp Gateway khả dụng với embedding hoặc các mô hình OpenAI trực tiếp mà không vô tình khiến các lượt app-server Codex gốc được tính phí qua API.

Các hồ sơ khóa API Codex được chỉ định rõ ràng và phương án dự phòng bằng khóa env của stdio cục bộ sử dụng đăng nhập app-server thay vì env được tiến trình con kế thừa. Các kết nối app-server WebSocket không nhận phương án dự phòng khóa API qua env của Gateway; hãy sử dụng hồ sơ xác thực rõ ràng hoặc tài khoản riêng của app-server từ xa.

Theo mặc định, các lần khởi chạy app-server stdio kế thừa môi trường tiến trình của OpenClaw. OpenClaw sở hữu cầu nối tài khoản app-server Codex và đặt CODEX_HOME thành một thư mục riêng cho từng tác tử bên dưới trạng thái OpenClaw của tác tử đó. Việc này giữ cấu hình, tài khoản, bộ nhớ đệm/dữ liệu plugin và trạng thái luồng của Codex trong phạm vi tác tử OpenClaw thay vì rò rỉ từ thư mục chính ~/.codex cá nhân của người vận hành.

Đặt appServer.homeScope: "user" để chia sẻ trạng thái Codex gốc với Codex Desktop và CLI. Chế độ thư mục chính người dùng cục bộ này hỗ trợ stdio được quản lý và cơ chế truyền Unix được chỉ định rõ ràng. Chế độ này sử dụng $CODEX_HOME khi được đặt và ~/.codex trong trường hợp còn lại, bao gồm xác thực, cấu hình, plugin và luồng gốc. OpenClaw bỏ qua cầu nối hồ sơ xác thực của mình cho app-server. Các lượt của chủ sở hữu đã được xác minh có thể dùng codex_threads để liệt kê (với bộ lọc search tùy chọn), đọc, phân nhánh, đổi tên, lưu trữ và bỏ lưu trữ các luồng đó. Hãy phân nhánh một luồng trước khi tiếp tục luồng đó trong OpenClaw; các tiến trình Codex độc lập không phối hợp những tiến trình ghi đồng thời vào cùng một luồng.

Lựa chọn bật homeScope đó áp dụng cho các phiên harness thông thường. Một cuộc trò chuyện được tạo thông qua Codex Sessions sẽ sử dụng kết nối giám sát riêng của nó, qua đó duy trì cấu hình xác thực và nhà cung cấp của kết nối gốc cho nhánh chính tắc và các lần tiếp tục trong tương lai.

Trong một cuộc trò chuyện được giám sát và khóa theo mô hình, codex_threads không thể gắn một nhánh khác hoặc lưu trữ luồng gốc đã liên kết của cuộc trò chuyện. Tính năng liệt kê và đọc chỉ siêu dữ liệu vẫn khả dụng. Việc đọc bản chép lời thô yêu cầu allowRawTranscripts; khi tùy chọn này bị vô hiệu hóa, tìm kiếm danh sách cũng bị từ chối vì tìm kiếm gốc có thể khớp với các bản xem trước bản chép lời. Việc đổi tên, bỏ lưu trữ, tạo nhánh tách rời và lưu trữ một luồng không liên quan, không thuộc sở hữu của một cuộc trò chuyện OpenClaw khác, yêu cầu allowWriteControls. Không tùy chọn nào có thể vượt qua một liên kết đã khóa.

OpenClaw không ghi lại HOME cho các lần khởi chạy app-server cục bộ thông thường. Các tiến trình con do Codex chạy như openclaw, gh, git, các CLI đám mây và lệnh shell nhìn thấy thư mục chính thông thường của tiến trình và có thể tìm thấy cấu hình cùng token trong thư mục chính người dùng. Codex cũng có thể phát hiện $HOME/.agents/skills và $HOME/.agents/plugins/marketplace.json; cơ chế phát hiện .agents đó được chủ ý chia sẻ với thư mục chính của người vận hành và tách biệt với trạng thái ~/.codex được cô lập.

Trong phạm vi tác tử mặc định, các plugin OpenClaw và ảnh chụp nhanh Skills của OpenClaw vẫn đi qua sổ đăng ký plugin và trình tải Skills riêng của OpenClaw; các tài nguyên ~/.codex Codex cá nhân thì không. Nếu bạn có Skills hoặc plugin CLI Codex hữu ích từ một thư mục chính Codex và muốn đưa chúng vào một tác tử OpenClaw được cô lập, hãy kiểm kê chúng một cách rõ ràng:

openclaw migrate codex --dry-runopenclaw migrate apply codex --yes

Nếu một bản triển khai cần cô lập thêm môi trường, hãy thêm các biến đó vào appServer.clearEnv:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],          },        },      },    },  },}

appServer.clearEnv chỉ ảnh hưởng đến tiến trình con app-server Codex được tạo. OpenClaw xóa CODEX_HOME và HOME khỏi danh sách này trong quá trình chuẩn hóa khởi chạy cục bộ: CODEX_HOME vẫn trỏ đến phạm vi tác tử hoặc người dùng đã chọn, còn HOME vẫn được kế thừa để các tiến trình con có thể sử dụng trạng thái thông thường trong thư mục chính người dùng.

Công cụ động

Theo mặc định, các công cụ động Codex sử dụng phương thức tải searchable, được cung cấp trong namespace openclaw với deferLoading: true. OpenClaw không cung cấp các công cụ động trùng lặp với thao tác không gian làm việc gốc của Codex hoặc bề mặt tìm kiếm công cụ riêng của Codex:

• read
• write
• edit
• apply_patch
• exec
• process
• update_plan
• tool_call
• tool_describe
• tool_search
• tool_search_code

Hầu hết các công cụ tích hợp OpenClaw còn lại, chẳng hạn như nhắn tin, phương tiện, Cron, trình duyệt, các Node, Gateway, heartbeat_respond và web_search, đều khả dụng thông qua tìm kiếm công cụ Codex trong namespace đó. Điều này giúp ngữ cảnh mô hình ban đầu nhỏ hơn. Một tập hợp nhỏ công cụ vẫn có thể được gọi trực tiếp bất kể codexDynamicToolsLoading, vì tìm kiếm công cụ Codex có thể không khả dụng hoặc chỉ phân giải được một tập hợp chỉ gồm trình kết nối: agents_list, sessions_spawn và sessions_yield. Các hướng dẫn dành cho nhà phát triển vẫn định hướng các tác tử con Codex thông thường đến spawn_agent gốc cho công việc tác tử con gốc Codex, trong khi sessions_spawn vẫn khả dụng cho việc ủy quyền OpenClaw hoặc ACP được chỉ định rõ ràng. Các phản hồi nguồn chỉ dùng công cụ tin nhắn cũng vẫn trực tiếp, vì đó là một hợp đồng điều khiển lượt.

Các công cụ được đánh dấu catalogMode: "direct-only", bao gồm công cụ computer của OpenClaw, được nhóm trong openclaw_direct. OpenClaw thêm namespace đó vào danh sách code_mode.direct_only_tool_namespaces của Codex mà không thay thế các mục do người vận hành cung cấp. Do đó, Codex cung cấp các công cụ đó dưới dạng DirectModelOnly trong các luồng thông thường và luồng chỉ dùng chế độ mã thay vì định tuyến chúng qua các lệnh gọi tools.* của Code Mode lồng nhau. Ranh giới này là bắt buộc đối với các kết quả chứa hình ảnh: quá trình tuần tự hóa Code Mode lồng nhau làm phẳng đầu ra hình ảnh thành văn bản, khiến ảnh chụp màn hình cần thiết cho thao tác máy tính tiếp theo bị loại bỏ.

Chỉ đặt codexDynamicToolsLoading: "direct" khi kết nối với một app-server Codex tùy chỉnh không thể tìm kiếm các công cụ động được trì hoãn hoặc khi gỡ lỗi toàn bộ tải trọng công cụ.

Thời gian chờ

Các lệnh gọi công cụ động do OpenClaw sở hữu được giới hạn độc lập với appServer.requestTimeoutMs. Mỗi yêu cầu Codex item/tool/call sử dụng giá trị hết thời gian khả dụng đầu tiên theo thứ tự sau:

• Đối số timeoutMs dương cho từng lệnh gọi.
• Đối với image_generate, agents.defaults.imageGenerationModel.timeoutMs.
• Đối với image_generate không được cấu hình thời gian chờ, giá trị mặc định 120 giây dành cho việc tạo hình ảnh.
• Đối với công cụ image dùng để hiểu nội dung đa phương tiện, tools.media.image.timeoutSeconds được chuyển đổi sang mili giây, hoặc giá trị mặc định 60 giây dành cho đa phương tiện. Đối với việc hiểu hình ảnh, giá trị này áp dụng cho chính yêu cầu và không bị giảm bởi công việc chuẩn bị trước đó.
• Đối với công cụ message, giá trị mặc định cố định là 120 giây.
• Giá trị mặc định 90 giây dành cho công cụ động.

Bộ giám sát thời gian này là ngân sách tổng thể cho item/tool/call động. Các thời gian chờ yêu cầu dành riêng cho nhà cung cấp chạy bên trong lệnh gọi đó và giữ nguyên ngữ nghĩa hết thời gian của riêng chúng. Ngân sách công cụ động được giới hạn ở 600000 ms. Khi hết thời gian, OpenClaw hủy tín hiệu công cụ nếu được hỗ trợ và trả về cho Codex một phản hồi công cụ động thất bại để lượt có thể tiếp tục thay vì khiến phiên bị kẹt ở trạng thái processing.

Sau khi Codex chấp nhận một lượt và sau khi OpenClaw phản hồi một yêu cầu máy chủ ứng dụng trong phạm vi lượt, bộ khung tích hợp kỳ vọng Codex tiếp tục xử lý lượt hiện tại và cuối cùng hoàn tất lượt gốc bằng turn/completed. Nếu máy chủ ứng dụng không có hoạt động trong appServer.turnCompletionIdleTimeoutMs, OpenClaw cố gắng ngắt lượt Codex, ghi lại chẩn đoán hết thời gian và giải phóng làn xử lý phiên OpenClaw để các tin nhắn trò chuyện tiếp theo không bị xếp hàng phía sau một lượt gốc đã lỗi thời.

Hầu hết thông báo chưa kết thúc của cùng một lượt đều vô hiệu hóa bộ giám sát ngắn này vì Codex đã chứng minh rằng lượt vẫn đang hoạt động. Việc bàn giao công cụ sử dụng ngân sách chờ sau công cụ dài hơn: sau khi OpenClaw trả về phản hồi item/tool/call, sau khi các mục công cụ gốc như commandExecution hoàn tất, sau khi hoàn tất custom_tool_call_output thô, cũng như sau tiến trình thô của trợ lý, hoàn tất suy luận thô hoặc tiến trình suy luận sau công cụ. Bộ bảo vệ sử dụng appServer.postToolRawAssistantCompletionIdleTimeoutMs khi được cấu hình; nếu không, giá trị mặc định là năm phút. Ngân sách sau công cụ này cũng kéo dài bộ giám sát tiến trình cho khoảng tổng hợp im lặng trước khi Codex phát sự kiện tiếp theo của lượt hiện tại. Sau các lần hoàn tất suy luận, hoàn tất agentMessage dạng bình luận và tiến trình suy luận thô hoặc tiến trình trợ lý trước công cụ có thể là một phản hồi cuối tự động, vì vậy chúng sử dụng bộ bảo vệ phản hồi sau tiến trình thay vì giải phóng làn xử lý phiên ngay lập tức. Chỉ các mục agentMessage cuối cùng/không phải bình luận đã hoàn tất và các lần hoàn tất trợ lý thô trước công cụ mới kích hoạt cơ chế giải phóng sau đầu ra của trợ lý: nếu sau đó Codex im lặng mà không có turn/completed, OpenClaw sẽ cố gắng ngắt lượt gốc và giải phóng làn xử lý phiên. Các lỗi máy chủ ứng dụng stdio an toàn để phát lại, bao gồm hết thời gian chờ hoàn tất lượt mà không có bằng chứng về trợ lý, công cụ, mục đang hoạt động hoặc tác dụng phụ, được thử lại một lần trong một lần chạy máy chủ ứng dụng mới. Các trường hợp hết thời gian không an toàn vẫn loại bỏ máy khách máy chủ ứng dụng bị kẹt và giải phóng làn xử lý phiên OpenClaw. Chúng cũng xóa liên kết luồng gốc đã lỗi thời thay vì tự động phát lại. Các trường hợp hết thời gian của bộ theo dõi hoàn tất hiển thị nội dung hết thời gian dành riêng cho Codex: trường hợp an toàn để phát lại cho biết phản hồi có thể chưa đầy đủ, còn trường hợp không an toàn yêu cầu người dùng xác minh trạng thái hiện tại trước khi thử lại. Chẩn đoán hết thời gian công khai bao gồm các trường cấu trúc như phương thức thông báo cuối cùng của máy chủ ứng dụng, mã định danh/loại/vai trò của mục phản hồi thô từ trợ lý, số lượng yêu cầu/mục đang hoạt động và trạng thái bộ theo dõi đã kích hoạt. Khi thông báo cuối cùng là một mục phản hồi thô từ trợ lý, chẩn đoán cũng bao gồm bản xem trước văn bản trợ lý có giới hạn. Chẩn đoán không bao gồm nội dung thô của lời nhắc hoặc công cụ.

Khám phá mô hình

Theo mặc định, Plugin Codex yêu cầu máy chủ ứng dụng cung cấp các mô hình khả dụng. Tính khả dụng của mô hình do máy chủ ứng dụng Codex quản lý, vì vậy danh sách có thể thay đổi khi OpenClaw nâng cấp phiên bản @openai/codex đi kèm hoặc khi một bản triển khai đặt appServer.command trỏ đến một tệp nhị phân Codex khác. Tính khả dụng cũng có thể phụ thuộc vào tài khoản. Sử dụng /codex models trên một Gateway đang chạy để xem danh mục trực tiếp của bộ khung tích hợp và tài khoản đó.

Nếu quá trình khám phá thất bại hoặc hết thời gian, OpenClaw sử dụng danh mục dự phòng đi kèm:

Điều chỉnh quá trình khám phá tại plugins.entries.codex.config.discovery:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },        },      },    },  },}

Tắt quá trình khám phá khi bạn muốn lúc khởi động không thăm dò Codex và chỉ sử dụng danh mục dự phòng:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: false,          },        },      },    },  },}

Các tệp khởi tạo không gian làm việc

Codex tự xử lý AGENTS.md thông qua cơ chế khám phá tài liệu dự án gốc. OpenClaw không ghi các tệp tài liệu dự án Codex tổng hợp hoặc phụ thuộc vào tên tệp dự phòng của Codex cho các tệp định hình cá tính, vì phương án dự phòng của Codex chỉ áp dụng khi thiếu AGENTS.md.

Để duy trì tính tương đồng với không gian làm việc OpenClaw, bộ khung tích hợp Codex chuyển tiếp các tệp khởi tạo khác dưới dạng chỉ dẫn dành cho nhà phát triển, nhưng không theo cách giống hệt nhau:

• TOOLS.md được chuyển tiếp dưới dạng chỉ dẫn dành cho nhà phát triển Codex được kế thừa, vì vậy các tác tử con Codex gốc được tạo trong lượt cũng có thể thấy tệp này.
• SOUL.md, IDENTITY.md và USER.md được chuyển tiếp dưới dạng chỉ dẫn cộng tác trong phạm vi lượt. Các tác tử con Codex gốc không kế thừa chúng, nhờ đó các lượt của tác tử con không tiếp nhận cá tính và hồ sơ người dùng của tác tử cha.
• Danh sách Skills OpenClaw đã nạp ở dạng rút gọn cũng được chuyển tiếp dưới dạng chỉ dẫn cộng tác dành cho nhà phát triển trong phạm vi lượt, vì vậy các tác tử con Codex gốc cũng không kế thừa danh sách này.
• Nội dung HEARTBEAT.md không được chèn; các lượt Heartbeat nhận một chỉ dẫn ở chế độ cộng tác để đọc tệp khi tệp tồn tại và không trống.
• Nội dung MEMORY.md từ không gian làm việc đã cấu hình của tác tử không được dán vào đầu vào lượt Codex gốc khi các công cụ bộ nhớ khả dụng cho không gian làm việc đó; khi tệp tồn tại, bộ khung tích hợp thêm một chỉ dẫn ngắn về bộ nhớ không gian làm việc vào chỉ dẫn cộng tác dành cho nhà phát triển trong phạm vi lượt và Codex nên sử dụng memory_search hoặc memory_get khi bộ nhớ lâu dài có liên quan. Nếu các công cụ bị tắt, tính năng tìm kiếm bộ nhớ không khả dụng hoặc không gian làm việc đang hoạt động khác với không gian làm việc bộ nhớ của tác tử, MEMORY.md sẽ sử dụng đường dẫn ngữ cảnh lượt có giới hạn thông thường.
• BOOTSTRAP.md, khi tồn tại, được chuyển tiếp dưới dạng ngữ cảnh tham chiếu đầu vào lượt OpenClaw.

Ghi đè bằng biến môi trường

Các ghi đè bằng biến môi trường vẫn khả dụng cho việc kiểm thử cục bộ:

• OPENCLAW_CODEX_APP_SERVER_BIN
• OPENCLAW_CODEX_APP_SERVER_ARGS
• OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
• OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
• OPENCLAW_CODEX_APP_SERVER_SANDBOX

OPENCLAW_CODEX_APP_SERVER_BIN bỏ qua tệp nhị phân được quản lý khi appServer.command chưa được đặt.

OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 đã bị loại bỏ. Thay vào đó, hãy sử dụng plugins.entries.codex.config.appServer.mode: "guardian", hoặc OPENCLAW_CODEX_APP_SERVER_MODE=guardian để kiểm thử cục bộ một lần. Cấu hình được ưu tiên cho các bản triển khai có thể lặp lại vì nó giữ hành vi của Plugin trong cùng tệp đã được rà soát với phần còn lại của thiết lập bộ khung tích hợp Codex.

Liên quan

• Bộ khung tích hợp Codex
• Môi trường chạy của bộ khung tích hợp Codex
• Giám sát Codex
• Plugin Codex gốc
• Codex Computer Use
• Nhà cung cấp OpenAI
• Tài liệu tham chiếu cấu hình