OpenAI

OpenClaw sử dụng một id nhà cung cấp duy nhất, openai, cho cả xác thực trực tiếp bằng khóa API và xác thực bằng gói đăng ký ChatGPT/Codex. openai/* là tuyến mô hình chuẩn. Đối với các lượt tác tử nhúng có chính sách runtime chưa được đặt hoặc là auto, các thông tin tuyến của OpenAI quyết định liệu OpenClaw có thể ngầm chọn runtime máy chủ ứng dụng Codex đi kèm hay không. Chỉ riêng tiền tố openai/* không chọn runtime.

• Mô hình tác tử - openai/* thông qua runtime được chọn bởi cấu hình agentRuntime rõ ràng hoặc chính sách tuyến ngầm định của OpenAI. Đăng nhập bằng xác thực Codex để sử dụng gói đăng ký ChatGPT/Codex, hoặc cấu hình hồ sơ xác thực bằng khóa API khi bạn muốn thanh toán dựa trên khóa.
• API OpenAI không dành cho tác tử - truy cập trực tiếp OpenAI Platform, tính phí theo mức sử dụng, thông qua OPENAI_API_KEY hoặc hồ sơ xác thực bằng khóa API openai.
• Cấu hình cũ - các tham chiếu codex/* và openai-codex/* được openclaw doctor --fix sửa thành openai/* cùng với agentRuntime.id: "codex" có phạm vi theo mô hình.

OpenAI hỗ trợ rõ ràng việc sử dụng OAuth của gói đăng ký trong các công cụ và quy trình làm việc bên ngoài như OpenClaw.

Theo dõi mức sử dụng và chi phí

OpenClaw tách biệt hạn ngạch gói đăng ký với việc tính phí API Platform:

• OAuth ChatGPT/Codex hiển thị gói đăng ký, các khoảng hạn ngạch và số dư tín dụng.
• OPENAI_ADMIN_KEY hiển thị 30 ngày chi phí tổ chức và mức sử dụng lượt hoàn thành do nhà cung cấp báo cáo trong mục Mức sử dụng của Control UI, bao gồm chi tiêu hằng ngày, tổng số yêu cầu/token, các mô hình hàng đầu và các danh mục chi phí.
• OPENAI_PROJECT_ID có thể giới hạn lịch sử Admin API trong một dự án.
• OpenClaw không bao giờ gửi OPENAI_API_KEY hoặc hồ sơ suy luận openai đến các API của tổ chức; những thông tin xác thực đó có thể thuộc về các điểm cuối tùy chỉnh, Azure hoặc cục bộ của tác tử.

Khóa Admin được chỉ định rõ ràng có độ ưu tiên cao hơn OAuth. Lịch sử do nhà cung cấp báo cáo không được hợp nhất với chi phí ước tính mà OpenClaw suy ra từ phiên; lịch sử này có thể bao gồm hoạt động API từ các máy khách khác và các điều chỉnh thanh toán phía nhà cung cấp.

Tài liệu Bảng điều khiển mức sử dụng API của OpenAI mô tả các yêu cầu về chủ sở hữu tổ chức và quyền Usage Dashboard rõ ràng để truy cập dữ liệu sử dụng.

Nhà cung cấp, mô hình, runtime và kênh là các lớp riêng biệt. Nếu những nhãn này bị nhầm 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

Runtime tác tử ngầm định

Khi chính sách agentRuntime của nhà cung cấp/mô hình chưa được đặt hoặc là auto, chính sách tuyến do nhà cung cấp OpenAI sở hữu sẽ chọn runtime ngầm định dựa trên điểm cuối và bộ điều hợp có hiệu lực:

agentRuntime.id không mặc định và được chỉ định rõ ràng của nhà cung cấp/mô hình vẫn có thẩm quyền quyết định. Ví dụ, agentRuntime.id: "openclaw" giữ một tuyến vốn đủ điều kiện dùng Codex trên OpenClaw, trong khi agentRuntime.id: "codex" yêu cầu Codex và từ chối khi tuyến có hiệu lực không được khai báo là tương thích với Codex. Việc chọn runtime không thay đổi loại thông tin xác thực hoặc cách tính phí: xác thực bằng khóa API Platform và xác thực bằng gói đăng ký ChatGPT/Codex vẫn tách biệt.

openclaw doctor --fix di chuyển các tham chiếu mô hình codex/* và openai-codex/* cũ, id hồ sơ xác thực Codex cũ và các mục thứ tự xác thực Codex cũ sang tuyến chuẩn openai. Các tham chiếu mô hình đã di chuyển nhận agentRuntime.id: "codex" có phạm vi theo mô hình; dùng auth.order.openai cho cấu hình thứ tự xác thực mới.

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

OpenClaw nhận dạng chính xác các id mô hình openai/gpt-5.6-sol, openai/gpt-5.6-terra và openai/gpt-5.6-luna. Cả ba đều cung cấp khả năng suy luận xhigh và max trong danh mục hiện tại. OpenAI mô tả Sol là tầng chủ lực, Terra là tầng cân bằng và Luna là tầng nhanh, có 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.

Với xác thực trực tiếp bằng khóa API OpenAI, id openai/gpt-5.6 không định danh là bí danh của Sol và là mặc định cho thiết lập mới. Danh mục Codex gốc không áp dụng bí danh API trực tiếp đó ở phía máy khách; tùy theo quyền truy cập không gian làm việc, danh mục có thể hiển thị chính xác các id Sol, Terra và Luna. Vì vậy, thiết lập OAuth ChatGPT/Codex mới sử dụng openai/gpt-5.6-sol. Kiểm tra tài khoản hiện tại bằng:

openclaw models list --provider openai

Quyền truy cập của tổ chức API và không gian làm việc Codex có thể khác nhau. Nếu GPT-5.6 không khả dụng, hãy chọn rõ ràng GPT-5.5:

openclaw models set openai/gpt-5.5

OpenClaw hiển thị lỗi truy cập từ thượng nguồn và không âm thầm thay thế lựa chọn GPT-5.6 bằng GPT-5.5.

Phạm vi hỗ trợ tính năng của OpenClaw

Embedding bộ nhớ

OpenClaw có thể dùng OpenAI hoặc endpoint embedding tương thích với OpenAI để lập chỉ mục memory_search và tạo embedding truy vấn:

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

Đối với các endpoint tương thích với OpenAI yêu cầu nhãn embedding bất đối xứng, hãy đặt queryInputType và documentInputType trong 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: embedding truy vấn dùng queryInputType; các đoạn bộ nhớ đã lập chỉ mục và quá trình 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

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.6" } } },}

{  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.6-sol

openclaw models list --provider openai

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

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },    },  },  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ộ khung app-server Codex gốc sử dụng các tham chiếu mô hình openai/* khi một tuyến HTTPS chính thức chính xác và đủ điều kiện chọn ngầm định bộ khung này, hoặc khi agentRuntime.id: "codex" của nhà cung cấp/mô hình chọn rõ ràng bộ khung này. Cơ chế xác thực vẫn dựa trên tài khoản. OpenClaw chọn phương thức xác thực theo thứ tự sau:

1. Các hồ sơ xác thực OpenAI đã sắp thứ tự cho tác tử, ưu tiên đặt trong 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ũ và thứ tự xác thực.
2. Tài khoản hiện có của app-server, chẳng hạn như phiên đăng nhập ChatGPT của Codex CLI cục bộ. Đối với thư mục chính tác tử cô lập mặc định, OpenClaw kết nối tài khoản CLI gốc đó vào app-server thông qua RPC đăng nhập; OpenClaw không chia sẻ cấu hình, plugin hoặc kho luồng của CLI.
3. Chỉ dành cho các lần khởi chạy app-server stdio cục bộ và chỉ khi app-server báo cáo không có tài khoản: CODEX_API_KEY, sau đó là OPENAI_API_KEY.

Phiên đă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 phép nhúng. Phương án dự phòng dùng khóa API từ môi trường chỉ áp dụng cho đường dẫn stdio cục bộ không có tài khoản; khóa này không bao giờ được gửi qua 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 loại CODEX_API_KEY và OPENAI_API_KEY khỏi tiến trình con app-server stdio được khởi tạo và thay vào đó gửi thông tin xác thực đã chọn qua RPC đăng nhập của app-server.

Khi hồ sơ gói đăng ký đó bị chặn do giới hạn sử dụng Codex, OpenClaw đánh dấu hồ sơ là bị chặn cho đến thời điểm đặt lại do Codex công bố và cho phép thứ tự xác thực chuyển sang hồ sơ openai:* tiếp theo mà không thay đổi mô hình đã chọn hoặc rời khỏi bộ khung Codex. Sau khi thời điểm đặt lại trôi qua, hồ sơ gói đăng ký sẽ lại đủ điều kiện.

Tạo hình ảnh

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

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

gpt-image-2 là lựa chọn mặc định để tạo hình ảnh từ văn bản và chỉnh sửa hình ảnh bằng OpenAI. gpt-image-1.5, gpt-image-1 và gpt-image-1-mini vẫn có thể dùng làm các ghi đè mô hình rõ ràng. Sử dụng openai/gpt-image-1.5 để tạo đầ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, hãy 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ũ vẫn được chấp nhận. OpenClaw cũng bảo vệ các tuyến OpenAI công khai và OAuth OpenAI Codex bằng cách ghi lại các yêu cầu trong suốt openai/gpt-image-2 mặc định thành gpt-image-1.5; Azure và các điểm cuối tùy chỉnh tương thích với OpenAI giữ nguyên tên triển khai/mô hình đã cấu hình.

Thiết lập tương tự cũng đượ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 "Một nhãn dán hình tròn màu đỏ đơn giản trên nền trong suốt" \  --json

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

Đối với các bản cài đặt dùng OAuth ChatGPT/Codex, hãy giữ nguyên tham chiếu openai/gpt-image-2. Khi một hồ sơ OAuth openai được cấu hình, OpenClaw phân giải token truy cập OAuth đã lưu trữ đó và gửi yêu cầu hình ảnh qua phần phụ trợ Codex Responses; OpenClaw không thử OPENAI_API_KEY trước hoặc âm thầm chuyển sang khóa API. Hãy cấu hình rõ ràng models.providers.openai bằng khóa API, URL cơ sở tùy chỉnh hoặc điểm cuối Azure khi bạn muốn sử dụng tuyến API OpenAI Images trực tiếp. Nếu điểm cuối hình ảnh tùy chỉnh đó nằm trên mạng LAN/địa chỉ riêng đáng tin cậy, hãy đặt thêm browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw vẫn chặn các điểm cuối hình ảnh tương thích với 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="Một áp phích ra mắt chỉn chu cho OpenClaw trên macOS" size=3840x2160 count=1

Tạo PNG có nền trong suốt:

/tool image_generate model=openai/gpt-image-1.5 prompt="Một nhãn dán hình tròn màu đỏ đơn giản trên nền trong suốt" outputFormat=png background=transparent

Chỉnh sửa:

/tool image_generate model=openai/gpt-image-2 prompt="Giữ nguyên hình dạng vật thể, thay đổi vật liệu thành thủy tinh trong mờ" image=/path/to/reference.png size=1024x1536

Tạo video

Plugin openai đi kèm đăng ký khả năng tạo video thông qua công cụ video_generate.

Các yêu cầu chuyển đổi hình ảnh thành video của OpenAI sử dụng POST /v1/videos với một hình ảnh input_reference. Các chỉnh sửa video đơn sử dụng POST /v1/videos/edits với video đã tải lên trong trường video.

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

Phần bổ sung cho prompt GPT-5

OpenClaw thêm một phần bổ sung dùng chung cho prompt GPT-5 đối với các mô hình thuộc họ GPT-5 trên nhà cung cấp openai (bao gồm các tham chiếu Codex cũ trước khi sửa chữa được chuẩn hóa thành openai/*). Các nhà cung cấp khác cũng phục vụ id mô hình thuộc họ GPT-5, chẳng hạn như các tuyến OpenRouter hoặc opencode, không nhận lớp phủ này; lớp phủ được kiểm soát theo id nhà cung cấp openai, không chỉ theo id mô hình. Các mô hình GPT-4.x cũ không bao giờ nhận lớp phủ này.

Bộ kiểm thử app-server Codex gốc không nhận hợp đồng hành vi về persona/kỷ luật sử dụng công cụ hoặc lớp phủ phong cách tương tác thân thiện thông qua chỉ dẫn dành cho nhà phát triển; Codex gốc giữ nguyên hành vi cơ sở, mô hình và tài liệu dự án do Codex sở hữu, còn OpenClaw vô hiệu hóa tính cách tích hợp sẵn của Codex cho các luồng gốc để các tệp tính cách trong không gian làm việc của agent tiếp tục có thẩm quyền. OpenClaw chỉ bổ sung ngữ cảnh thời gian chạy vào các luồng Codex gốc: phân phối qua kênh, công cụ động của OpenClaw, ủy quyền ACP, ngữ cảnh không gian làm việc và Skills của OpenClaw. Văn bản hướng dẫn Heartbeat từ cùng phần bổ sung này là ngoại lệ duy nhất: các lượt Heartbeat của Codex gốc vẫn nhận văn bản này, được chèn dưới dạng chỉ dẫn cộng tác chuyên biệt thay vì thông qua hook bổ sung prompt dùng chung.

Phần bổ sung 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 sử dụng công cụ, hình thức đầu ra, kiểm tra hoàn thành và xác minh trên các prompt tương ứng do OpenClaw tập hợp. Hành vi trả lời theo từng kênh và tin nhắn im lặng vẫn nằm trong prompt hệ thống dùng chung của OpenClaw và chính sách phân phối đi. Lớp phong cách tương tác thân thiện tách 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",          },        ],      },    },  },}

Các điểm cuối Azure OpenAI

Nhà cung cấp openai đi kèm có thể nhắm đến 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 trong models.providers.openai.baseUrl và tự động chuyển sang cấu trúc yêu cầu của Azure.

Sử dụng Azure OpenAI khi:

• Bạn đã có gói đăng ký, hạn ngạch hoặc thỏa thuận doanh nghiệp Azure OpenAI
• Bạn cần khả năng lưu trú dữ liệu theo khu vực hoặc các biện pháp 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 đối tượng thuê 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, hãy 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 dạng các hậu tố máy chủ Azure sau 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áy chủ Azure được nhận dạng, OpenClaw:

• Gửi tiêu đề api-key thay cho Authorization: Bearer
• Sử dụng các đường dẫn theo phạm vi triển khai (/openai/deployments/{deployment}/...)
• Nối thêm ?api-version=... vào mỗi yêu cầu
• Sử dụng thời gian chờ yêu cầu mặc định là 600s 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 đè giá trị mặc định này.

Các URL cơ sở khác (OpenAI công khai, proxy tương thích OpenAI) vẫn sử dụng cấu trúc yêu cầu hình ảnh OpenAI tiêu chuẩn.

Phiên bản API

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

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

Giá trị mặc định là 2024-12-01-preview khi biến 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 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 thông tin Azure, không phải id mô hình OpenAI công khai.

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

/tool image_generate model=openai/gpt-image-2-prod prompt="Một áp phích gọn gàng" size=1024x1024 count=1

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

Phạm vi cung cấp theo khu vực

Tính năng tạo hình ảnh Azure hiện chỉ có ở 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 mô hình 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 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 bắt nguồ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 thất bại với lỗi xác thực, hãy kiểm tra tập hợp tham số được phiên bản triển khai và API cụ thể của bạn hỗ trợ trong cổng thông tin Azure.

Cấu hình nâng cao

Các ví dụ params theo từng mô hình bên dưới định hình yêu cầu nhà cung cấp nhúng của OpenClaw. Việc cấu hình chúng là hành vi yêu cầu do người dùng chỉ định, vì vậy một tuyến auto vốn đủ điều kiện vẫn chạy trên OpenClaw thay vì ngầm chọn Codex. Bộ khung app-server Codex gốc sở hữu cơ chế truyền tải và cài đặt yêu cầu riêng; agentRuntime.id: "codex" tường minh sẽ đóng khi lỗi nếu tuyến hiệu lực không được khai báo là tương thích Codex.

{  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: "default" },    },  },}

Liên quan