OpenAI

OpenAI cung cấp API dành 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 nhân lập trình trong gói ChatGPT thông qua các client Codex của OpenAI. OpenClaw dùng một id nhà cung cấp, openai, cho cả hai dạng xác thực.

OpenClaw dùng openai/* làm tuyến mô hình OpenAI chính tắc. Các lượt tác nhân 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 nhân như hình ảnh, embedding, giọng nói và realtime.

• Mô hình tác nhân - các mô hình openai/* thông qua runtime Codex; đăng nhập bằng xác thực Codex để dùng thuê bao ChatGPT/Codex, hoặc cấu hình một hồ sơ 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 nhân - 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 quy trình thiết lập khóa API OpenAI.
• Cấu hình cũ - các tham chiếu mô hình Codex cũ được openclaw doctor --fix sửa thành openai/* kèm runtime Codex.

OpenAI hỗ trợ rõ ràng việc dùng OAuth thuê bao trong các công cụ và quy trình làm việc 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, hãy đọc Runtime tác nhân trước khi thay đổi cấu hình.

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 tham chiếu mô hình openai/* trong khi các hồ sơ xác thực trỏ tới thông tin đăng nhập khóa API hoặc OAuth ChatGPT/Codex. Dùng auth.order.openai cho cấu hình; openclaw doctor --fix ghi lại các tham chiếu mô hình Codex cũ, id hồ sơ xác thực Codex cũ và thứ tự xác thực Codex cũ sang tuyến OpenAI chính tắc.

Bản xem trước giới hạn GPT-5.6

OpenClaw nhận diện ba id mô hình GPT-5.6 công khai:

• openai/gpt-5.6-sol
• openai/gpt-5.6-terra
• openai/gpt-5.6-luna

Cả ba đều cung cấp suy luận max trong catalog app-server Codex hiện tại. Thông báo ra mắt của OpenAI mô tả Sol là tầng chủ lực, Terra là tầng cân bằng và Luna là tầng nhanh, chi phí thấp hơn. Xem thông báo ra mắt GPT-5.6 và hướng dẫn truy cập bản xem trước.

Quyền truy cập được đưa vào danh sách cho phép trong thời gian xem trước và có thể được cấp riêng cho API và Codex. Chỉ một gói ChatGPT trả phí không cấp quyền truy cập. OpenClaw giữ openai/gpt-5.5 làm mặc định; chọn một tham chiếu GPT-5.6 khi không có quyền truy cập sẽ trả về lỗi truy cập từ upstream thay vì âm thầm chuyển dự phòng.

Phạm vi tính năng OpenClaw

Embedding bộ nhớ

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

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

Đối với các endpoint tương thích OpenAI yêu cầu nhãn embedding bất đối xứng, hãy đặt queryInputType và documentInputType dưới memorySearch. OpenClaw chuyển tiếp chúng dưới dạng các trường yêu cầu input_type riêng theo nhà cung cấp: embedding truy vấn dùng queryInputType; các đoạn bộ nhớ được 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ớ để có ví dụ đầy đủ.

Bắt đầu

Chọn phương thức xác thực bạn muố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: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },}

{  env: { OPENAI_API_KEY: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/chat-latest" } } },}

openclaw onboard --auth-choice openai

openclaw models auth login --provider openai

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

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

openclaw models list --provider openai

{  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:user@example.com",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openaiopenclaw 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

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openaiopenclaw models status --probe --probe-provider openai

openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

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

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

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

1. Các hồ sơ xác thực OpenAI đã sắp xếp cho tác tử, tốt nhất là dưới auth.order.openai. Chạy openclaw doctor --fix để di chuyển các id hồ sơ xác thực Codex kế thừa cũ hơn và thứ tự xác thực Codex kế thừa.
2. Tài khoản hiện có của app-server, chẳng hạn như một lượt đă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, rồi OPENAI_API_KEY, khi app-server báo cáo không có tài khoản và vẫn yêu cầu xác thực OpenAI.

Điều đó có nghĩa là một lượt đăng nhập gói đă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 mô hình OpenAI trực tiếp hoặc embedding. Phương án dự phòng khóa API qua env chỉ là đường dẫn stdio cục bộ không có tài khoản; nó không được gửi tới các kết nối app-server WebSocket. Khi một hồ sơ Codex kiểu gói đă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 sinh ra và gửi thông tin xác thực đã chọn qua RPC đăng nhập app-server. Khi hồ sơ gói đăng ký đó bị chặn bởi giới hạn sử dụng Codex, OpenClaw có thể xoay sang hồ sơ khóa API openai:* đã sắp xếp tiếp theo mà không thay đổi mô hình đã chọn hoặc rời khỏi bộ harness Codex. Khi thời điểm đặt lại gói đăng ký trôi qua, hồ sơ gói đăng ký sẽ đủ điều kiện trở lại.

Tạo hình ảnh

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

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

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

Đối với yêu cầu nền trong suốt, agent 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 triển khai/mô hình đã cấu hình của chúng.

Cùng thiết lập này được cung cấp cho các lần chạy CLI không giao diện:

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 có sẵn như một bí danh dành riêng cho OpenAI. Dùng --quality low|medium|high|auto khi bạn cần kiểm soát chất lượng và chi phí OpenAI Images. Dùng --openai-moderation low|auto để truyền gợi ý kiểm duyệt dành riêng cho nhà cung cấp của OpenAI từ image generate hoặc image edit.

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

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 đi kèm đăng ký tính năng tạo video thông qua công cụ video_generate.

Yêu cầu ảnh thành video của OpenAI dùng POST /v1/videos với một input_reference ảnh. Chỉnh sửa một video dùng POST /v1/videos/edits với video đã tải lên trong trường video.

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

Đóng góp prompt GPT-5

OpenClaw thêm một đóng góp prompt GPT-5 dùng chung cho các lần chạy thuộc họ GPT-5 trên các bề mặt prompt do OpenClaw lắp ráp. Nó áp dụng theo id mô hình, vì vậy các tuyến OpenClaw/nhà cung cấp như tham chiếu cũ trước sửa chữa (tham chiếu Codex GPT-5.5 cũ), 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 lớp phủ. Các mô hình GPT-4.x cũ hơn thì không.

Bộ khai thác Codex gốc đi kèm không nhận lớp phủ GPT-5 OpenClaw này thông qua chỉ dẫn nhà phát triển của app-server Codex. Codex gốc giữ hành vi cơ sở, mô hình và tài liệu dự án do Codex sở hữu, trong khi OpenClaw tắt tính cách tích hợp của Codex cho các luồng gốc để các tệp tính cách workspace của agent vẫn có thẩm quyền. OpenClaw chỉ đóng góp ngữ cảnh runtime như phân phối kênh, công cụ động OpenClaw, ủy quyền ACP, ngữ cảnh workspace và Skills OpenClaw.

Đóng góp GPT-5 thêm một hợp đồng hành vi có gắn thẻ cho 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 trên các prompt do OpenClaw lắp ráp phù hợp. Hành vi trả lời theo kênh và tin nhắn im lặng vẫn nằm trong prompt hệ thống OpenClaw dùng chung và chính sách phân phối gửi đi. Lớp phong cách 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", speakerVoice: "coral" },      },    },  },}

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

Endpoint Azure OpenAI

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

Dùng Azure OpenAI khi:

• Bạn đã có gói đăng ký, quota, hoặc thỏa thuận doanh nghiệp Azure OpenAI
• Bạn cần 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 trong một tenancy Azure hiện có

Cấu hình

Để tạo ảnh qua Azure bằng provider openai đi kèm, trỏ models.providers.openai.baseUrl đến 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 diện các hậu tố máy chủ Azure này cho tuyến tạo ảnh Azure:

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

Với các yêu cầu tạo ảnh trên máy chủ Azure được nhận diện, 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}/...)
• Gắn ?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 ả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ữ hình dạng yêu cầu ảnh OpenAI 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 ảnh 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 mô hình là tên triển khai

Azure OpenAI liên kết mô hình với các triển khai. Đối với yêu cầu tạo ảnh Azure được định tuyến qua provider 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 mô hình OpenAI công khai.

Nếu bạn tạo một triển khai tên 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 tên triển khai tương tự áp dụng cho các lệnh gọi tạo ảnh được định tuyến qua provider openai đi kèm.

Tính khả dụng theo khu vực

Tạo ảnh Azure hiện chỉ khả dụng ở một số khu vực (ví dụ eastus2, swedencentral, polandcentral, westus3, uaenorth). 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 mô hình cụ thể được cung cấp ở 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 tham số ả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 trên gpt-image-2) hoặc chỉ cung cấp chúng trên các phiên bản mô hình cụ thể. Những khác biệt này đến từ Azure và mô hình nền tảng, không phải OpenClaw. Nếu một yêu cầu Azure lỗi với lỗi xác thực hợp lệ, 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: "auto", fastAutoOnSeconds: 30 } },      },    },  },}

{  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: {      embeddedAgent: { executionContract: "strict-agentic" },    },  },}

Liên quan