Bộ khung Codex

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Plugin này thay đổi gì

• bắt đầu dùng Codex cho mọi mô hình OpenAI
• chuyển các tham chiếu mô hình openai-codex/* sang runtime gốc
• đặt ACP/acpx làm đường dẫn Codex mặc định
• chuyển nóng các phiên hiện có đã ghi nhận runtime PI
• thay thế việc phân phối kênh, tệp phiên, lưu trữ hồ sơ xác thực hoặc định tuyến tin nhắn của OpenClaw

• before_prompt_build
• before_compaction, after_compaction
• llm_input, llm_output
• before_tool_call, after_tool_call
• before_message_write cho các bản ghi transcript phản chiếu
• before_agent_finalize thông qua chuyển tiếp Stop của Codex
• agent_end

​

Bản đồ tuyến

• openai-codex/* trả lời “PI nên dùng tuyến nhà cung cấp/xác thực nào?”
• agentRuntime.id: "codex" trả lời “vòng lặp nào nên thực thi lượt nhúng này?”
• /codex ... trả lời “cuộc trò chuyện Codex gốc nào nên được trò chuyện này liên kết hoặc điều khiển?”
• ACP trả lời “tiến trình harness bên ngoài nào acpx nên khởi chạy?”

​

Chọn đúng tiền tố mô hình

​

Ý nghĩa cảnh báo của doctor

• Plugin codex đi kèm được bật hoặc được cho phép
• mô hình chính của một tác nhân là openai-codex/*
• runtime hiệu lực của tác nhân đó không phải là codex

• Không cần thay đổi nếu bạn dự định dùng OAuth ChatGPT/Codex thông qua PI.
• Đổi mô hình thành openai/<model> và đặt agentRuntime.id: "codex" nếu bạn dự định thực thi gốc trên máy chủ ứng dụng.
• Các phiên hiện có vẫn cần /new hoặc /reset sau khi thay đổi runtime, vì ghim runtime của phiên là cố định.

​

Yêu cầu

• OpenClaw có Plugin codex đi kèm sẵn dùng.
• Máy chủ ứng dụng Codex 0.125.0 hoặc mới hơn. Plugin đi kèm quản lý mặc định một tệp nhị phân máy chủ ứng dụng Codex tương thích, nên các lệnh codex cục bộ trên PATH không ảnh hưởng đến khởi động harness bình thường.
• Xác thực Codex sẵn dùng cho tiến trình máy chủ ứng dụng hoặc cho cầu nối xác thực Codex của OpenClaw.

​

Cấu hình tối thiểu

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
}

{
  plugins: {
    allow: ["codex"],
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}

​

Thêm Codex cùng với các mô hình khác

• Đặt Codex trên một tác tử chuyên dụng với agentRuntime.id: "codex".
• Giữ tác tử mặc định trên agentRuntime.id: "auto" và phương án dự phòng PI cho cách dùng nhà cung cấp hỗn hợp thông thường.
• Chỉ dùng các tham chiếu codex/* cũ để tương thích. Cấu hình mới nên ưu tiên openai/* cùng một chính sách runtime Codex rõ ràng.

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      agentRuntime: {
        id: "auto",
        fallback: "pi",
      },
    },
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "codex",
        name: "Codex",
        model: "openai/gpt-5.5",
        agentRuntime: {
          id: "codex",
        },
      },
    ],
  },
}

• Tác tử main mặc định dùng đường dẫn nhà cung cấp thông thường và phương án dự phòng tương thích PI.
• Tác tử codex dùng harness app-server Codex.
• Nếu Codex bị thiếu hoặc không được hỗ trợ cho tác tử codex, lượt chạy sẽ thất bại thay vì âm thầm dùng PI.

​

Định tuyến lệnh tác tử

​

Triển khai chỉ dùng Codex

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
        fallback: "none",
      },
    },
  },
}

OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run

​

Codex theo từng tác tử

{
  agents: {
    defaults: {
      agentRuntime: {
        id: "auto",
        fallback: "pi",
      },
    },
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "codex",
        name: "Codex",
        model: "openai/gpt-5.5",
        agentRuntime: {
          id: "codex",
          fallback: "none",
        },
      },
    ],
  },
}

​

Khám phá mô hình

• GPT-5.5
• GPT-5.4 mini
• GPT-5.2

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

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

​

Kết nối và chính sách app-server

codex app-server --listen stdio://

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

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

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

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

• 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

​

Sử dụng máy tính

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          computerUse: {
            autoInstall: true,
          },
        },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
        fallback: "none",
      },
    },
  },
}

• /codex computer-use status
• /codex computer-use install
• /codex computer-use install --source <marketplace-source>
• /codex computer-use install --marketplace-path <path>

​

Công thức thường dùng

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

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            approvalPolicy: "on-request",
            approvalsReviewer: "auto_review",
            sandbox: "workspace-write",
          },
        },
      },
    },
  },
}

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://gateway-host:39175",
            headers: {
              "X-OpenClaw-Agent": "main",
            },
          },
        },
      },
    },
  },
}

​

Lệnh Codex

• /codex status hiển thị kết nối app-server trực tiếp, mô hình, tài khoản, giới hạn tốc độ, máy chủ MCP và skills.
• /codex models liệt kê các mô hình app-server Codex trực tiếp.
• /codex threads [filter] liệt kê các thread Codex gần đây.
• /codex resume <thread-id> gắn phiên OpenClaw hiện tại vào một thread Codex hiện có.
• /codex compact yêu cầu app-server Codex nén thread đã gắn.
• /codex review bắt đầu đánh giá gốc của Codex cho thread đã gắn.
• /codex diagnostics [note] hỏi trước khi gửi phản hồi chẩn đoán Codex cho thread đã gắn.
• /codex computer-use status kiểm tra Plugin Computer Use và máy chủ MCP đã cấu hình.
• /codex computer-use install cài đặt Plugin Computer Use đã cấu hình và tải lại máy chủ MCP.
• /codex account hiển thị trạng thái tài khoản và giới hạn tốc độ.
• /codex mcp liệt kê trạng thái máy chủ MCP của app-server Codex.
• /codex skills liệt kê các skills của app-server Codex.

​

Quy trình gỡ lỗi thường dùng

1. Chạy /diagnostics bad tool choice after image upload hoặc một ghi chú ngắn khác mô tả điều bạn đã thấy.
2. Phê duyệt yêu cầu chẩn đoán một lần. Việc phê duyệt tạo tệp zip chẩn đoán Gateway cục bộ và, vì phiên đang dùng harness Codex, cũng gửi gói phản hồi Codex liên quan tới máy chủ OpenAI.
3. Sao chép phản hồi chẩn đoán đã hoàn tất vào báo cáo lỗi hoặc thread hỗ trợ. Phản hồi bao gồm đường dẫn gói cục bộ, tóm tắt quyền riêng tư, id phiên OpenClaw, id thread Codex và một dòng Inspect locally cho từng thread Codex.
4. Nếu bạn muốn tự gỡ lỗi lần chạy, hãy chạy lệnh Inspect locally được in ra trong terminal. Lệnh này có dạng codex resume <thread-id> và mở thread Codex gốc để bạn có thể kiểm tra cuộc trò chuyện, tiếp tục cục bộ, hoặc hỏi Codex vì sao nó chọn một công cụ hoặc kế hoạch cụ thể.

​

Kiểm tra một luồng Codex từ CLI

codex resume <thread-id>

​

Ranh giới hook

​

Hợp đồng hỗ trợ V1

​

Công cụ, phương tiện, và Compaction

​

Khắc phục sự cố

​

Liên quan

• Plugin harness tác tử
• Runtime tác tử
• Nhà cung cấp mô hình
• Nhà cung cấp OpenAI
• Trạng thái
• Móc Plugin
• Tham chiếu cấu hình
• Kiểm thử