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

• POST /v1/chat/completions
• Cùng cổng với Gateway (ghép kênh WS + HTTP): http://<gateway-host>:<port>/v1/chat/completions

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/responses

​

Xác thực

• xác thực bằng bí mật dùng chung (gateway.auth.mode="token" hoặc "password"): Authorization: Bearer <token-or-password>
• xác thực HTTP mang danh tính đáng tin cậy (gateway.auth.mode="trusted-proxy"): định tuyến qua proxy nhận biết danh tính đã cấu hình và để nó chèn các header danh tính bắt buộc
• xác thực mở qua ingress riêng tư (gateway.auth.mode="none"): không cần header xác thực

• Khi gateway.auth.mode="token", dùng gateway.auth.token (hoặc OPENCLAW_GATEWAY_TOKEN).
• Khi gateway.auth.mode="password", dùng gateway.auth.password (hoặc OPENCLAW_GATEWAY_PASSWORD).
• Khi gateway.auth.mode="trusted-proxy", yêu cầu HTTP phải đến từ một nguồn proxy đáng tin cậy đã cấu hình; proxy loopback cùng máy chủ yêu cầu bật rõ ràng gateway.auth.trustedProxy.allowLoopback = true.
• Các caller nội bộ cùng máy chủ bỏ qua proxy có thể dùng gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD làm phương án dự phòng trực tiếp cục bộ. Bất kỳ bằng chứng header Forwarded, X-Forwarded-*, hoặc X-Real-IP nào sẽ giữ yêu cầu trên đường dẫn trusted-proxy thay thế.
• Nếu gateway.auth.rateLimit được cấu hình và xảy ra quá nhiều lỗi xác thực, điểm cuối trả về 429 kèm Retry-After.

​

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

• Xác thực bearer HTTP ở đây không phải là mô hình phạm vi hẹp theo từng người dùng.
• Token/mật khẩu Gateway hợp lệ cho điểm cuối này nên được xem như thông tin xác thực của chủ sở hữu/operator.
• Các yêu cầu chạy qua cùng đường dẫn tác nhân control-plane như các hành động operator đáng tin cậy.
• Không có ranh giới công cụ riêng cho non-owner/theo từng người dùng trên điểm cuối này; một khi caller vượt qua xác thực Gateway ở đây, OpenClaw xem caller đó là operator đáng tin cậy cho gateway này.
• Với các chế độ xác thực bằng bí mật dùng chung (token và password), điểm cuối khôi phục các mặc định operator đầy đủ bình thường ngay cả khi caller gửi header x-openclaw-scopes hẹp hơn.
• Các chế độ HTTP mang danh tính đáng tin cậy (ví dụ xác thực proxy đáng tin cậy hoặc gateway.auth.mode="none") tôn trọng x-openclaw-scopes khi có mặt và nếu không thì quay về tập phạm vi operator mặc định bình thường.
• Nếu chính sách tác nhân đích cho phép các công cụ nhạy cảm, điểm cuối này có thể dùng chúng.
• Chỉ giữ điểm cuối này trên loopback/tailnet/ingress riêng tư; không phơi bày trực tiếp ra internet công cộng.

• gateway.auth.mode="token" hoặc "password" + Authorization: Bearer ...
  • chứng minh đang sở hữu bí mật operator gateway dùng chung
  • bỏ qua x-openclaw-scopes hẹp hơn
  • khôi phục tập phạm vi operator mặc định đầy đủ: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • xem các lượt chat trên điểm cuối này là lượt do chủ sở hữu gửi
• các chế độ HTTP mang danh tính đáng tin cậy (ví dụ xác thực proxy đáng tin cậy, hoặc gateway.auth.mode="none" trên ingress riêng tư)
  • xác thực một danh tính đáng tin cậy bên ngoài hoặc ranh giới triển khai
  • tôn trọng x-openclaw-scopes khi header có mặt
  • quay về tập phạm vi operator mặc định bình thường khi header vắng mặt
  • chỉ mất ngữ nghĩa chủ sở hữu khi caller thu hẹp phạm vi một cách rõ ràng và bỏ qua operator.admin
  • yêu cầu operator.admin cho các điều khiển yêu cầu cấp chủ sở hữu như x-openclaw-model

​

Khi nào dùng điểm cuối này

• Ưu tiên cách này thay vì thêm một kênh tích hợp sẵn mới khi tích hợp của bạn chỉ là một bề mặt operator/client khác cho cùng gateway.
• Với client di động native kết nối trực tiếp tới gateway từ xa, hãy ưu tiên WebChat hoặc Giao thức Gateway và triển khai luồng bootstrap thiết bị ghép cặp/device-token để 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 một Plugin kênh khi bạn đang tích hợp một mạng nhắn tin bên ngoài có người dùng, phòng, phân phối Webhook hoặc transport gửi đi riêng. Xem Xây dựng plugin.

​

Hợp đồng mô hình ưu tiên tác nhân

• model: "openclaw" định tuyến tới tác nhân mặc định đã cấu hình.
• model: "openclaw/default" cũng định tuyến tới tác nhân mặc định đã cấu hình.
• model: "openclaw/<agentId>" định tuyến tới một tác nhân cụ thể.

• x-openclaw-model: <provider/model-or-bare-id> ghi đè mô hình backend cho tác nhân đã chọn. Caller bearer dùng bí mật dùng chung có thể dùng header này. Caller mang danh tính, chẳng hạn yêu cầu trusted-proxy hoặc ingress riêng tư không xác thực có x-openclaw-scopes, cần operator.admin; caller chỉ có quyền ghi nhận 403 missing scope: operator.admin.
• x-openclaw-agent-id: <agentId> vẫn được hỗ trợ như một ghi đè tương thích.
• x-openclaw-session-key: <sessionKey> điều khiển định tuyến phiên một cách rõ ràng. Giá trị không được dùng các namespace phiên nội bộ dành riêng như subagent:, cron:, hoặc acp:; các yêu cầu đó bị từ chối với 400 invalid_request_error.
• x-openclaw-message-channel: <channel> đặt ngữ cảnh kênh ingress tổng hợp cho các prompt và chính sách nhận biết kênh.

• model: "openclaw:<agentId>"
• model: "agent:<agentId>"

​

Bật điểm cuối

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

​

Tắt điểm cuối

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

​

Hành vi phiên

​

Vì sao bề mặt này quan trọng

• Hầu hết thiết lập Open WebUI, LobeChat và LibreChat mong đợi /v1/models.
• Nhiều hệ thống RAG mong đợi /v1/embeddings.
• Các client chat OpenAI hiện có thường có thể bắt đầu với /v1/chat/completions.
• Các client thiên về tác nhân hơn ngày càng ưu tiên /v1/responses.

​

Danh sách mô hình và định tuyến tác nhân

​

Streaming (SSE)

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

​

Hợp đồng công cụ chat

​

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

• tools: mảng { "type": "function", "function": { ... } }
• tool_choice: "auto", "none", "required", hoặc { "type": "function", "function": { "name": "..." } }
• các lượt theo sau messages[*].role: "tool"
• messages[*].tool_call_id để liên kết kết quả công cụ trở lại một lệnh gọi công cụ trước đó
• max_completion_tokens: số; giới hạn theo mỗi lệnh gọi cho tổng token hoàn tất (bao gồm token suy luận). Tên trường OpenAI Chat Completions hiện tại; được ưu tiên khi cả max_completion_tokens và max_tokens được gửi.
• max_tokens: số; bí danh cũ được chấp nhận để tương thích ngược. Bị bỏ qua khi max_completion_tokens cũng có mặt.
• temperature: số; nhiệt độ lấy mẫu theo best-effort được chuyển tiếp tới provider upstream qua kênh stream-param của tác nhân.
• top_p: số; lấy mẫu nucleus theo best-effort được chuyển tiếp tới provider upstream qua kênh stream-param của tác nhân.
• frequency_penalty: số; penalty tần suất theo best-effort được chuyển tiếp tới provider upstream qua kênh stream-param của tác nhân. Khoảng hợp lệ: -2.0 đến 2.0. Trả về 400 invalid_request_error cho giá trị ngoài khoảng.
• presence_penalty: số; penalty hiện diện theo best-effort được chuyển tiếp tới provider upstream qua kênh stream-param của tác nhân. Khoảng hợp lệ: -2.0 đến 2.0. Trả về 400 invalid_request_error cho giá trị ngoài khoảng.
• seed: số (số nguyên); seed theo best-effort được chuyển tiếp tới provider upstream qua kênh stream-param của tác nhân. Trả về 400 invalid_request_error cho giá trị không phải số nguyên.
• stop: chuỗi hoặc mảng tối đa 4 chuỗi; chuỗi dừng theo best-effort được chuyển tiếp tới provider upstream qua kênh stream-param của tác nhân. Trả về 400 invalid_request_error nếu có hơn 4 chuỗi hoặc mục không phải chuỗi/rỗng.

​

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

• tools không phải mảng
• các mục công cụ không phải function
• 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 tools được cung cấp

​

Hình dạng phản hồi công cụ không streaming

• các mục choices[0].finish_reason = "tool_calls"
• choices[0].message.tool_calls[] với:
  • id
  • type: "function"
  • function.name
  • function.arguments (chuỗi JSON)

​

Hình dạng phản hồi công cụ streaming

• delta vai trò assistant ban đầu
• các delta bình luận assistant tùy chọn
• một hoặc nhiều chunk delta.tool_calls mang danh tính công cụ và các mảnh đối số
• chunk cuối cùng với finish_reason: "tool_calls"
• data: [DONE]

​

Vòng lặp theo dõi công cụ

• tin nhắn gọi công cụ trước đó của assistant
• một hoặc nhiều tin nhắn role: "tool" với tool_call_id khớp

​

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 Gateway của bạn
• Model: openclaw/default

• GET /v1/models nên liệt kê openclaw/default
• Open WebUI nên dùng openclaw/default làm id model chat
• Nếu bạn muốn một nhà cung cấp/model backend cụ thể cho tác tử đó, hãy đặt model mặc định thông thường của tác tử hoặc gửi x-openclaw-model từ bên gọi dùng shared-secret hoặc bên gọi có danh tính với operator.admin

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

​

Ví dụ

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"}]
  }'

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"}]
  }'

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"}]
  }'

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

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

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/models trả về các mục tiêu tác tử OpenClaw, không phải catalog nhà cung cấp thô.
• openclaw/default luôn hiện diện để một id ổn định hoạt động trên nhiều môi trường.
• Các ghi đè nhà cung cấp/model backend thuộc về x-openclaw-model, không phải trường OpenAI model. Trên các đường dẫn xác thực HTTP có danh tính, header này yêu cầu operator.admin.
• /v1/embeddings hỗ trợ input là chuỗi hoặc mảng chuỗi.

​

Liên quan

• Tham chiếu cấu hình
• OpenAI