Hoàn tất trò chuyện OpenAI

Gateway có thể cung cấp một bề mặt Chat Completions nhỏ tương thích với OpenAI. Tính năng này bị tắt theo mặc định.

Sau khi được bật, Gateway cung cấp tất cả các endpoint sau trên cùng cổng với Gateway (ghép kênh WS + HTTP):

Các yêu cầu chạy như một lượt chạy agent Gateway thông thường (cùng đường dẫn mã với openclaw agent), vì vậy cơ chế định tuyến, quyền và cấu hình khớp với Gateway của bạn.

Bật endpoint

{  gateway: {    http: {      endpoints: {        chatCompletions: { enabled: true },      },    },  },}

Đặt enabled: false (hoặc bỏ qua thuộc tính này) để tắt.

Ranh giới bảo mật (quan trọng)

Hãy coi endpoint này là quyền truy cập đầy đủ của người vận hành đối với phiên bản Gateway:

• Token/mật khẩu Gateway hợp lệ cho endpoint này tương đương với thông tin xác thực của chủ sở hữu/người vận hành, không phải phạm vi hẹp dành riêng cho từng người dùng.
• Các yêu cầu chạy qua cùng đường dẫn agent của mặt phẳng điều khiển như các thao tác của người vận hành đáng tin cậy, vì vậy nếu chính sách của agent đích cho phép các công cụ nhạy cảm, endpoint này có thể sử dụng chúng.
• Chỉ duy trì endpoint này trên local loopback/tailnet/điểm vào riêng tư. Không để endpoint tiếp xúc với Internet công cộng.

Ma trận xác thực:

Xem Phạm vi của người vận hành, Bảo mật và Truy cập từ xa.

Xác thực

Sử dụng cấu hình xác thực của Gateway (xem Xác thực proxy đáng tin cậy để biết chi tiết về chế độ đó):

Lưu ý:

• Bên gọi trên cùng máy chủ bỏ qua proxy của Gateway trusted-proxy có thể trực tiếp dùng gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD làm phương án dự phòng. Mọi bằng chứng từ header Forwarded, X-Forwarded-* hoặc X-Real-IP sẽ khiến yêu cầu tiếp tục đi theo đường dẫn trusted-proxy.
• Nếu gateway.auth.rateLimit được cấu hình và có quá nhiều lần xác thực thất bại, endpoint trả về 429 cùng header Retry-After.

Khi nào nên sử dụng endpoint này

• Ưu tiên endpoint này thay vì thêm một kênh tích hợp mới khi phần tích hợp của bạn chỉ là một bề mặt người vận hành/máy khách khác cho cùng Gateway.
• Với máy khách di động gốc kết nối trực tiếp đến Gateway từ xa, hãy ưu tiên WebChat hoặc Giao thức Gateway với quy trình khởi tạo thiết bị đã ghép nối/token thiết bị, để thiết bị không cần token/mật khẩu HTTP dùng chung.
• Thay vào đó, hãy xây dựng Plugin kênh khi tích hợp một mạng nhắn tin bên ngoài có người dùng, phòng, cơ chế phân phối Webhook hoặc phương thức truyền gửi đi riêng. Xem Xây dựng Plugin.

Hợp đồng mô hình ưu tiên agent

OpenClaw coi trường model của OpenAI là một đích agent, không phải mã định danh mô hình thô của nhà cung cấp.

Các header yêu cầu tùy chọn:

/v1/models liệt kê các đích agent cấp cao nhất (openclaw, openclaw/default, openclaw/<agentId>), không phải các mô hình backend của nhà cung cấp hay agent con; agent con vẫn là cấu trúc liên kết thực thi nội bộ. Nếu bạn bỏ qua x-openclaw-model, agent đã chọn sẽ chạy với mô hình được cấu hình thông thường của nó.

/v1/embeddings sử dụng cùng các mã định danh model của đích agent. Gửi x-openclaw-model (từ bên gọi sử dụng bí mật dùng chung hoặc bên gọi có mang danh tính với operator.admin) để chọn một mô hình nhúng cụ thể; nếu không, yêu cầu sẽ sử dụng thiết lập nhúng thông thường của agent đã chọn.

Hành vi phiên

Theo mặc định, endpoint không lưu trạng thái cho từng yêu cầu (mỗi lần gọi sẽ tạo một khóa phiên mới).

Nếu yêu cầu chứa chuỗi user của OpenAI, Gateway sẽ suy ra một khóa phiên ổn định từ chuỗi đó để các lần gọi lặp lại có thể dùng chung một phiên agent. Đối với ứng dụng tùy chỉnh, hãy tái sử dụng cùng một giá trị user cho mỗi luồng hội thoại; tránh các mã định danh cấp tài khoản trừ khi bạn muốn nhiều cuộc hội thoại/thiết bị dùng chung một phiên OpenClaw. Chỉ sử dụng x-openclaw-session-key khi cần kiểm soát định tuyến rõ ràng trên nhiều máy khách/luồng, với các khóa do ứng dụng sở hữu và không sử dụng các không gian tên dành riêng nêu trên.

Giới hạn yêu cầu (cấu hình)

Có thể tinh chỉnh các giá trị mặc định trong gateway.http.endpoints.chatCompletions:

{  gateway: {    http: {      endpoints: {        chatCompletions: {          enabled: true,          maxBodyBytes: 20000000,          maxImageParts: 8,          maxTotalImageBytes: 20000000,          images: {            allowUrl: false,            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],            allowedMimes: [              "image/jpeg",              "image/png",              "image/gif",              "image/webp",              "image/heic",              "image/heif",            ],            maxBytes: 10485760,            maxRedirects: 3,            timeoutMs: 10000,          },        },      },    },  },}

Giá trị mặc định khi bỏ qua:

Các nguồn image_url HEIC/HEIF được chấp nhận và chuẩn hóa thành JPEG trước khi chuyển đến nhà cung cấp thông qua bộ xử lý ảnh dùng chung của OpenClaw (Rastermill); bộ xử lý này dùng trình chuyển đổi hệ thống (sips, ImageMagick, GraphicsMagick hoặc ffmpeg) làm phương án dự phòng cho các định dạng cần hỗ trợ codec bên ngoài.

Lưu ý bảo mật: việc đưa một tên máy chủ vào danh sách cho phép không vô hiệu hóa cơ chế chặn địa chỉ IP riêng/nội bộ. Đối với các Gateway tiếp xúc với Internet, hãy áp dụng biện pháp kiểm soát lưu lượng mạng đi ra bên cạnh các cơ chế bảo vệ ở cấp ứng dụng. Xem Bảo mật.

Hợp đồng công cụ trò chuyện

/v1/chat/completions hỗ trợ một tập con công cụ hàm tương thích với các ứng dụng trò chuyện OpenAI phổ biến.

Các trường yêu cầu được hỗ trợ

Tất cả các trường lấy mẫu và giới hạn token đều đi qua cùng một kênh tham số luồng của tác nhân và được chuyển tiếp theo khả năng tốt nhất:

• Giới hạn token: tên trường trên giao thức truyền được chọn theo cơ chế truyền tải của nhà cung cấp: max_completion_tokens cho các điểm cuối thuộc họ OpenAI, max_tokens cho các nhà cung cấp chỉ chấp nhận tên cũ (Mistral, Chutes).
• stop ánh xạ tới trường dừng của cơ chế truyền tải: stop cho các phần phụ trợ Chat Completions, stop_sequences cho Anthropic. OpenAI Responses API không có tham số dừng, vì vậy stop không được áp dụng cho các mô hình dựa trên Responses.
• Phần phụ trợ Codex Responses dựa trên ChatGPT sử dụng cấu hình lấy mẫu cố định ở phía máy chủ và loại bỏ temperature/top_p (cùng với max_output_tokens, metadata, prompt_cache_retention, service_tier) trước khi yêu cầu đến phần phụ trợ đó.

Các biến thể không được hỗ trợ

Trả về 400 invalid_request_error đối với:

• tools không phải mảng, phần tử công cụ không phải hàm, hoặc thiếu tool.function.name
• các biến thể tool_choice như allowed_tools và custom
• các giá trị tool_choice.function.name không khớp với công cụ đã cung cấp

Đối với tool_choice: "required" và tool_choice được ghim vào một hàm, điểm cuối sẽ thu hẹp tập công cụ hàm phía máy khách được cung cấp, yêu cầu môi trường thời gian chạy gọi một công cụ máy khách trước khi phản hồi và trả về lỗi nếu phản hồi của tác nhân không có lệnh gọi công cụ máy khách có cấu trúc tương ứng. Điều này áp dụng cho danh sách HTTP tools do bên gọi cung cấp, không phải mọi công cụ nội bộ của tác nhân OpenClaw.

Cấu trúc phản hồi công cụ không truyền phát

Khi tác nhân gọi công cụ, phản hồi sử dụng:

• choices[0].finish_reason = "tool_calls"
• các phần tử choices[0].message.tool_calls[] gồm id, type: "function", function.name, function.arguments (chuỗi JSON)
• Nội dung giải thích của trợ lý trước lệnh gọi công cụ trong choices[0].message.content (có thể rỗng)

Cấu trúc phản hồi công cụ truyền phát

Khi stream: true, các lệnh gọi công cụ đến dưới dạng những đoạn SSE tăng dần: một delta vai trò trợ lý ban đầu, các delta nội dung giải thích tùy chọn của trợ lý, một hoặc nhiều đoạn delta.tool_calls chứa danh tính công cụ và các phần đối số, sau đó là đoạn cuối cùng với finish_reason: "tool_calls" và data: [DONE].

Nếu stream_options.include_usage=true, một đoạn thông tin sử dụng cuối luồng được phát ra trước [DONE].

Vòng lặp tiếp nối công cụ

Sau khi nhận được tool_calls, hãy thực thi các hàm được yêu cầu và gửi một yêu cầu tiếp theo bao gồm thông báo gọi công cụ trước đó của trợ lý cùng một hoặc nhiều thông báo role: "tool" có tool_call_id tương ứng. Thao tác này tiếp tục cùng một vòng lặp suy luận của tác nhân để tạo ra câu trả lời cuối cùng.

Truyền phát (SSE)

Đặt stream: true để nhận Sự kiện do máy chủ gửi:

• Content-Type: text/event-stream
• Mỗi dòng sự kiện có dạng data: <json>
• Luồng kết thúc bằng data: [DONE]

Thiết lập nhanh Open WebUI

• URL cơ sở: http://127.0.0.1:18789/v1
• URL cơ sở Docker trên macOS: http://host.docker.internal:18789/v1
• Khóa API: token bearer của Gateway
• Mô hình: openclaw/default

Hành vi dự kiến: GET /v1/models liệt kê openclaw/default và Open WebUI sử dụng giá trị đó làm mã mô hình trò chuyện. Đối với một nhà cung cấp/mô hình phần phụ trợ cụ thể, hãy đặt mô hình mặc định thông thường của tác nhân hoặc gửi x-openclaw-model (bên gọi dùng bí mật dùng chung hoặc bên gọi mang danh tính với operator.admin).

Kiểm tra nhanh:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

Nếu lệnh đó trả về openclaw/default, hầu hết cấu hình Open WebUI có thể kết nối bằng cùng URL cơ sở và token.

Ví dụ

Phiên ổn định cho một cuộc hội thoại của ứng dụng:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "user": "conv:YOUR_CONVERSATION_ID",    "messages": [{"role":"user","content":"Summarize my tasks for today"}]  }'

Dùng lại cùng giá trị user trong các lệnh gọi sau cho cuộc hội thoại đó để tiếp tục cùng một phiên tác nhân.

Không truyền phát:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "messages": [{"role":"user","content":"hi"}]  }'

Truyền phát:

curl -N http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/gpt-5.4' \  -d '{    "model": "openclaw/research",    "stream": true,    "messages": [{"role":"user","content":"hi"}]  }'

Liệt kê các mô hình:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

Truy xuất một mô hình:

curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \  -H 'Authorization: Bearer YOUR_TOKEN'

Tạo vector nhúng:

curl -sS http://127.0.0.1:18789/v1/embeddings \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/text-embedding-3-small' \  -d '{    "model": "openclaw/default",    "input": ["alpha", "beta"]  }'

/v1/embeddings hỗ trợ input dưới dạng chuỗi hoặc mảng chuỗi.

Liên quan

• Tham chiếu cấu hình
• Phạm vi của người vận hành
• OpenAI