OpenAI

OpenAI cung cấp các 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 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 đó 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 mặc định chạy qua runtime app-server Codex gốc; 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, embedding, 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 openai-codex để dùng gói đăng ký ChatGPT/Codex, hoặc cấu hình một hồ sơ khóa API openai-codex khi bạn chủ đí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 quy trình thiết lập khóa API OpenAI.
• Cấu hình cũ - các tham chiếu mô hình openai-codex/* được openclaw doctor --fix sửa 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 tầng 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ể dùng thay thế cho nhau:

Điều này có nghĩa là một cấu hình có thể chủ đích chứa cả tham chiếu mô hình openai/* và hồ sơ xác thực openai-codex. openclaw doctor --fix viết lại các tham chiếu mô hình openai-codex/* cũ thành tuyến mô hình OpenAI chuẩn.

# 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 việc lập chỉ mục memory_search và embedding 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, 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 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à 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: "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" },
      agentRuntime: { id: "codex" },
    },
  },
}

openclaw models status
openclaw models auth list --provider openai-codex
openclaw config get agents.defaults.model --json
openclaw config get agents.defaults.agentRuntime --json

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

openclaw doctor --fix
openclaw config validate

openclaw models auth login --provider openai-codex
openclaw 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

Bộ chạy app-server Codex gốc dùng tham chiếu model openai/* cộng với cấu hình runtime bị bỏ qua hoặc 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. Một hồ sơ xác thực OpenClaw openai-codex rõ ràng được gắn với agent.
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, 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à đă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 model OpenAI trực tiếp hoặc embeddings. Dự phòng API key trong 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.

# Tạo ảnh

Plugin openai đi kèm đăng ký tạo ảnh thông qua công cụ image_generate. Nó hỗ trợ cả tạo ảnh bằng API key OpenAI và tạo ảnh bằng OAuth Codex 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 ảnh từ văn bản OpenAI và chỉnh sửa ảnh. gpt-image-1.5, gpt-image-1, và gpt-image-1-mini vẫn dùng được dưới dạng 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, 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 provider 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à OAuth OpenAI Codex 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ữ tên triển khai/model đã 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 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 bí danh dành riêng cho OpenAI.

Với các cài đặt OAuth Codex, 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 access token OAuth đã lưu đó và gửi yêu cầu ảnh thông qua backend Codex Responses. Nó không thử OPENAI_API_KEY trước hoặc âm thầm dự phòng sang API key cho yêu cầu đó. Cấu hình models.providers.openai rõ ràng với API key, 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 vào đó. Nếu endpoint ả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 vẫn chặn các endpoint ảnh tương thích OpenAI riêng tư/nội bộ trừ khi có lựa 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ạo video thông qua công cụ video_generate.

{
  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 họ GPT-5 trên nhiều provider. Nó áp dụng theo id model, vì vậy openai/gpt-5.5, các tham chiếu cũ trước khi sử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 nhận cùng lớp phủ. Các model GPT-4.x cũ hơn thì không.

Bộ chạy Codex gốc đi kèm dùng cùng hành vi GPT-5 và lớp phủ Heartbeat thông qua hướng dẫn developer của app-server Codex, vì vậy các phiên openai/gpt-5.x bị buộc đi qua agentRuntime.id: "codex" giữ cùng hướng dẫn theo dõi đến cùng và Heartbeat chủ động, dù Codex sở hữu phần còn lại của prompt bộ chạy.

Phần đóng góp GPT-5 bổ sung 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 prompt 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 phù hợp. 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", 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ể trỏ đế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 dạng yêu cầu của Azure.

Dùng Azure OpenAI khi:

• Bạn đã có đă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 biện pháp kiểm soát tuân thủ mà 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 ả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 diện các hậu tố máy chủ Azure này cho route tạo ảnh Azure:

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

Đối với 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 deployment (/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 ả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ữ nguyên dạng yêu cầu ả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 ảnh Azure:

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

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

# Tên mô hình là tên deployment

Azure OpenAI liên kết mô hình với deployment. Đối với yêu cầu tạo ả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 deployment Azure 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 deployment 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 tên deployment tương tự áp dụng cho các lệnh gọi tạo ảnh được định tuyến qua nhà cung cấp openai đi kèm.

# Khả dụng theo khu vực

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

# Cấu hình nâng cao

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

// Disable warm-up
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { openaiWsWarmup: false },
        },
      },
    },
  },
}

{
  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