OpenAI

OpenAI cung cấp API cho nhà phát triển cho các mô hình GPT, và Codex cũng có sẵn dưới dạng tác tử lập trình theo gói ChatGPT thông qua các client Codex của OpenAI. OpenClaw giữ các bề mặt này tách biệt để cấu hình luôn dễ dự đoán.

OpenClaw dùng openai/* làm tuyến mô hình OpenAI chuẩn. Các lượt tác tử nhúng trên mô hình OpenAI chạy qua runtime app-server Codex gốc theo mặc định; xác thực bằng khóa API OpenAI trực tiếp vẫn có sẵn cho các bề mặt OpenAI không phải tác tử như hình ảnh, embeddings, giọng nói và realtime.

• Mô hình tác tử - các mô hình openai/* thông qua runtime Codex; đăng nhập bằng xác thực Codex để dùng gói đăng ký ChatGPT/Codex, hoặc cấu hình một bản dự phòng khóa API OpenAI tương thích với Codex khi bạn chủ ý muốn xác thực bằng khóa API.
• API OpenAI không phải tác tử - truy cập OpenAI Platform trực tiếp với tính phí theo mức sử dụng thông qua OPENAI_API_KEY hoặc onboarding khóa API OpenAI.
• Cấu hình cũ - các tham chiếu mô hình openai-codex/* được sửa bởi openclaw doctor --fix thành openai/* cộng với runtime Codex.

OpenAI hỗ trợ rõ ràng việc dùng OAuth theo gói đăng ký trong các công cụ và workflow bên ngoài như OpenClaw.

Nhà cung cấp, mô hình, runtime và kênh là các lớp riêng biệt. Nếu các nhãn đó đang bị trộn lẫn với nhau, hãy đọc Runtime tác tử trước khi thay đổi cấu hình.

Lựa chọn nhanh

Bản đồ tên gọi

Các tên tương tự nhau nhưng không thể thay thế cho nhau:

Điều này có nghĩa là một cấu hình có thể chủ ý chứa các tham chiếu mô hình openai/* trong khi các hồ sơ xác thực vẫn trỏ đến thông tin xác thực tương thích với Codex. Ưu tiên auth.order.openai cho cấu hình mới; các hồ sơ openai-codex:* hiện có và auth.order.openai-codex vẫn được hỗ trợ. openclaw doctor --fix ghi lại các tham chiếu mô hình cũ openai-codex/* sang tuyến mô hình OpenAI chuẩn.

Phạm vi tính năng OpenClaw

Embeddings bộ nhớ

OpenClaw có thể dùng OpenAI, hoặc một endpoint embedding tương thích OpenAI, cho việc lập chỉ mục memory_search và embeddings truy vấn:

{  agents: {    defaults: {      memorySearch: {        provider: "openai",        model: "text-embedding-3-small",      },    },  },}

Với các endpoint tương thích OpenAI yêu cầu nhãn embedding bất đối xứng, đặt queryInputType và documentInputType bên dưới memorySearch. OpenClaw chuyển tiếp chúng dưới dạng các trường yêu cầu input_type dành riêng cho nhà cung cấp: embeddings truy vấn dùng queryInputType; các đoạn bộ nhớ đã lập chỉ mục và lập chỉ mục theo lô dùng documentInputType. Xem Tham chiếu cấu hình bộ nhớ để biết ví dụ đầy đủ.

Bắt đầu

Chọn phương thức xác thực bạn ưu tiên và làm theo các bước thiết lập.

openclaw onboard --auth-choice openai-api-key

openclaw onboard --openai-api-key "$OPENAI_API_KEY"

openclaw models list --provider openai

{  env: { OPENAI_API_KEY: "sk-..." },  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },}

{  env: { OPENAI_API_KEY: "sk-..." },  agents: { defaults: { model: { primary: "openai/chat-latest" } } },}

openclaw onboard --auth-choice openai-codex

openclaw models auth login --provider openai-codex

openclaw models auth login --provider openai-codex --device-code

openclaw config set agents.defaults.model.primary openai/gpt-5.5

openclaw models list --provider openai-codex

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

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.5" },    },  },  auth: {    order: {      openai: [        "openai-codex:[email protected]",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openai-codexopenclaw config get agents.defaults.model --jsonopenclaw config get models.providers.openai.agentRuntime --json

openclaw models status --agent <id>openclaw models auth list --agent <id> --provider openai-codex

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openai-codexopenclaw models status --probe --probe-provider openai-codex

{  models: {    providers: {      "openai-codex": {        models: [{ id: "gpt-5.5", contextTokens: 160000 }],      },    },  },}

Xác thực app-server Codex gốc

Harness app-server Codex gốc dùng các tham chiếu model openai/* kèm cấu hình runtime bị bỏ qua hoặc provider/model agentRuntime.id: "codex", nhưng auth của nó vẫn dựa trên tài khoản. OpenClaw chọn auth theo thứ tự này:

1. Các hồ sơ auth OpenAI theo thứ tự cho tác nhân, ưu tiên dưới auth.order.openai. Các hồ sơ openai-codex:* hiện có và auth.order.openai-codex vẫn hợp lệ cho bản cài đặt cũ hơn.
2. Tài khoản hiện có của app-server, chẳng hạn như đăng nhập ChatGPT bằng 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 app-server báo cáo không có tài khoản và vẫn yêu cầu OpenAI auth.

Điều đó có nghĩa là đăng nhập đăng ký ChatGPT/Codex cục bộ không bị thay thế chỉ vì tiến trình gateway cũng có OPENAI_API_KEY cho các model OpenAI trực tiếp hoặc embeddings. Dự phòng API-key qua env chỉ là đường dẫn stdio cục bộ không có tài khoản; nó không được gửi đến các kết nối app-server WebSocket. Khi một hồ sơ Codex kiểu đăng ký được chọn, OpenClaw cũng giữ CODEX_API_KEY và OPENAI_API_KEY khỏi tiến trình con app-server stdio được tạo và gửi thông tin đăng nhập đã chọn thông qua RPC đăng nhập app-server. Khi hồ sơ đăng ký đó bị chặn bởi một giới hạn sử dụng Codex, OpenClaw có thể xoay sang hồ sơ API-key openai:* theo thứ tự tiếp theo mà không thay đổi model đã chọn hoặc rời khỏi harness Codex. Sau khi thời gian đặt lại đăng ký trôi qua, hồ sơ đăng ký lại đủ điều kiện.

Tạo hình ảnh

Plugin openai đi kèm đăng ký tạo hình ảnh thông qua công cụ image_generate. Nó hỗ trợ cả tạo hình ảnh bằng OpenAI API-key và tạo hình ảnh bằng Codex OAuth thông qua cùng tham chiếu model openai/gpt-image-2.

{  agents: {    defaults: {      imageGenerationModel: { primary: "openai/gpt-image-2" },    },  },}

gpt-image-2 là mặc định cho cả tạo hình ảnh từ văn bản OpenAI và chỉnh sửa hình ảnh. gpt-image-1.5, gpt-image-1 và gpt-image-1-mini vẫn có thể dùng như các ghi đè model rõ ràng. Dùng openai/gpt-image-1.5 cho đầu ra PNG/WebP nền trong suốt; API gpt-image-2 hiện tại từ chối background: "transparent".

Với yêu cầu nền trong suốt, tác nhân nên gọi image_generate với model: "openai/gpt-image-1.5", outputFormat: "png" hoặc "webp", và background: "transparent"; tùy chọn nhà cung cấp openai.background cũ hơn vẫn được chấp nhận. OpenClaw cũng bảo vệ các tuyến OpenAI công khai và OpenAI Codex OAuth bằng cách viết lại các yêu cầu trong suốt mặc định openai/gpt-image-2 thành gpt-image-1.5; Azure và các endpoint tương thích OpenAI tùy chỉnh giữ nguyên tên deployment/model đã cấu hình của chúng.

Thiết lập tương tự được cung cấp cho các lượt chạy CLI headless:

openclaw infer image generate \  --model openai/gpt-image-1.5 \  --output-format png \  --background transparent \  --prompt "A simple red circle sticker on a transparent background" \  --json

Dùng cùng các cờ --output-format và --background với openclaw infer image edit khi bắt đầu từ một tệp đầu vào. --openai-background vẫn khả dụng dưới dạng alias riêng cho OpenAI.

Với các bản cài đặt Codex OAuth, hãy giữ cùng tham chiếu openai/gpt-image-2. Khi một hồ sơ OAuth openai-codex được cấu hình, OpenClaw phân giải OAuth access token đã lưu đó và gửi yêu cầu hình ảnh qua backend Codex Responses. Nó không thử OPENAI_API_KEY trước hoặc âm thầm chuyển về một API key cho yêu cầu đó. Hãy cấu hình models.providers.openai rõ ràng bằng API key, URL cơ sở tùy chỉnh hoặc endpoint Azure khi bạn muốn tuyến OpenAI Images API trực tiếp thay thế. Nếu endpoint hình ảnh tùy chỉnh đó nằm trên LAN/địa chỉ riêng đáng tin cậy, cũng đặt browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw giữ các endpoint hình ảnh tương thích OpenAI riêng tư/nội bộ bị chặn trừ khi lựa chọn tham gia này có mặt.

Tạo:

/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1

Tạo PNG trong suốt:

/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

Chỉnh sửa:

/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536

Tạo video

Plugin openai được đóng gói kèm đăng ký tạo video thông qua công cụ video_generate.

{  agents: {    defaults: {      videoGenerationModel: { primary: "openai/sora-2" },    },  },}

Đóng góp lời nhắc GPT-5

OpenClaw thêm một đóng góp lời nhắc GPT-5 dùng chung cho các lượt chạy thuộc họ GPT-5 trên nhiều nhà cung cấp. Nó áp dụng theo mã định danh mô hình, nên openai/gpt-5.5, các tham chiếu cũ trước khi sửa chữa như openai-codex/gpt-5.5, openrouter/openai/gpt-5.5, opencode/gpt-5.5, và các tham chiếu GPT-5 tương thích khác đều nhận cùng một lớp phủ. Các mô hình GPT-4.x cũ hơn thì không.

Bộ khai thác Codex gốc được đóng gói kèm sử dụng cùng hành vi GPT-5 và lớp phủ Heartbeat thông qua chỉ dẫn dành cho nhà phát triển của máy chủ ứng dụng Codex, nên các phiên openai/gpt-5.x được định tuyến qua Codex vẫn giữ cùng hướng dẫn theo đến cùng và Heartbeat chủ động, dù Codex sở hữu phần còn lại của lời nhắc bộ khai thác.

Đóng góp GPT-5 thêm một hợp đồng hành vi có gắn thẻ cho việc duy trì persona, an toàn thực thi, kỷ luật công cụ, hình dạng đầu ra, kiểm tra hoàn tất và xác minh. Hành vi trả lời theo kênh và tin nhắn im lặng vẫn nằm trong lời nhắc hệ thống OpenClaw dùng chung và chính sách gửi đi. Hướng dẫn GPT-5 luôn được bật cho các mô hình khớp. Lớp kiểu tương tác thân thiện là riêng biệt và có thể cấu hình.

{  agents: {    defaults: {      promptOverlays: {        gpt5: { personality: "friendly" },      },    },  },}

openclaw config set agents.defaults.promptOverlays.gpt5.personality off

Giọng nói và lời nói

{  messages: {    tts: {      providers: {        openai: { model: "gpt-4o-mini-tts", voice: "coral" },      },    },  },}

{  tools: {    media: {      audio: {        models: [          {            type: "provider",            provider: "openai",            model: "gpt-4o-transcribe",          },        ],      },    },  },}

Endpoint Azure OpenAI

Nhà cung cấp openai đi kèm có thể nhắm tới một tài nguyên Azure OpenAI để tạo hình ảnh bằng cách ghi đè URL cơ sở. Trên đường dẫn tạo hình ảnh, OpenClaw phát hiện tên máy chủ Azure trên models.providers.openai.baseUrl và tự động chuyển sang dạng yêu cầu của Azure.

Dùng Azure OpenAI khi:

• Bạn đã có gói đăng ký, hạn mức, hoặc thỏa thuận doanh nghiệp Azure OpenAI
• Bạn cần vùng lưu trú dữ liệu theo khu vực hoặc các kiểm soát tuân thủ do Azure cung cấp
• Bạn muốn giữ lưu lượng bên trong một tenancy Azure hiện có

Cấu hình

Để tạo hình ảnh Azure thông qua nhà cung cấp openai đi kèm, trỏ models.providers.openai.baseUrl tới tài nguyên Azure của bạn và đặt apiKey thành khóa Azure OpenAI (không phải khóa OpenAI Platform):

{  models: {    providers: {      openai: {        baseUrl: "https://<your-resource>.openai.azure.com",        apiKey: "<azure-openai-api-key>",      },    },  },}

OpenClaw nhận dạng các hậu tố máy chủ Azure này cho tuyến tạo hình ảnh Azure:

• *.openai.azure.com
• *.services.ai.azure.com
• *.cognitiveservices.azure.com

Đối với các yêu cầu tạo hình ảnh trên một máy chủ Azure được nhận dạng, OpenClaw:

• Gửi header api-key thay vì Authorization: Bearer
• Dùng các đường dẫn theo phạm vi triển khai (/openai/deployments/{deployment}/...)
• Thêm ?api-version=... vào mỗi yêu cầu
• Dùng thời gian chờ yêu cầu mặc định 600 giây cho các lệnh gọi tạo hình ảnh Azure. Các giá trị timeoutMs theo từng lệnh gọi vẫn ghi đè mặc định này.

Các URL cơ sở khác (OpenAI công khai, proxy tương thích OpenAI) giữ dạng yêu cầu hình ảnh OpenAI tiêu chuẩn.

Phiên bản API

Đặt AZURE_OPENAI_API_VERSION để ghim một phiên bản Azure preview hoặc GA cụ thể cho đường dẫn tạo hình ảnh của Azure:

export AZURE_OPENAI_API_VERSION="2024-12-01-preview"

Mặc định là 2024-12-01-preview khi biến này chưa được đặt.

Tên model là tên triển khai

Azure OpenAI liên kết model với các triển khai. Đối với các yêu cầu tạo hình ảnh Azure được định tuyến qua nhà cung cấp openai đi kèm, trường model trong OpenClaw phải là tên triển khai Azure mà bạn đã cấu hình trong cổng Azure, không phải id model OpenAI công khai.

Nếu bạn tạo một triển khai tên là gpt-image-2-prod phục vụ gpt-image-2:

/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1

Quy tắc dùng tên triển khai tương tự cũng áp dụng cho các lệnh gọi tạo hình ảnh được định tuyến qua nhà cung cấp openai đi kèm.

Tình trạng khả dụng theo khu vực

Tạo hình ảnh Azure hiện chỉ khả dụng ở một số khu vực (ví dụ eastus2, swedencentral, polandcentral, westus3, uaenorth). Hãy kiểm tra danh sách khu vực hiện tại của Microsoft trước khi tạo triển khai, và xác nhận model cụ thể được cung cấp trong khu vực của bạn.

Khác biệt về tham số

Azure OpenAI và OpenAI công khai không phải lúc nào cũng chấp nhận cùng các tham số hình ảnh. Azure có thể từ chối các tùy chọn mà OpenAI công khai cho phép (ví dụ một số giá trị background nhất định trên gpt-image-2) hoặc chỉ cung cấp chúng trên các phiên bản model cụ thể. Những khác biệt này đến từ Azure và model nền tảng, không phải OpenClaw. Nếu một yêu cầu Azure thất bại với lỗi xác thực, hãy kiểm tra tập tham số được hỗ trợ bởi triển khai và phiên bản API cụ thể của bạn trong cổng Azure.

Cấu hình nâng cao

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: { transport: "auto" },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { fastMode: true } },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { serviceTier: "priority" } },      },    },  },}

{  agents: {    defaults: {      models: {        "azure-openai-responses/gpt-5.5": {          params: { responsesServerCompaction: true },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            responsesServerCompaction: true,            responsesCompactThreshold: 120000,          },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: { responsesServerCompaction: false },        },      },    },  },}

{  agents: {    defaults: {      embeddedPi: { executionContract: "strict-agentic" },    },  },}

Liên quan