Hoàn tất trò chuyện của OpenAI

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• 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 shared-secret (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à để proxy đó chèn các header danh tính bắt buộc
• xác thực mở qua ngõ vào 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 đặt rõ gateway.auth.trustedProxy.allowLoopback = true.
• Nếu gateway.auth.rateLimit được cấu hình và xảy ra quá nhiều lần xác thực thất bại, đ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 owner/operator.
• Các yêu cầu chạy qua cùng đường dẫn agent 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 không phải owner/theo từng người dùng trên điểm cuối này; sau 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 shared-secret (token và password), điểm cuối khôi phục các mặc định toàn quyền operator thông 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 trusted proxy 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ề bộ phạm vi mặc định operator thông thường.
• Nếu chính sách agent đí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/ngõ vào 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 quyền sở hữu shared gateway operator secret
  • bỏ qua x-openclaw-scopes hẹp hơn
  • khôi phục bộ 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 của owner-sender
• các chế độ HTTP mang danh tính đáng tin cậy (ví dụ xác thực trusted proxy, hoặc gateway.auth.mode="none" trên ngõ vào 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ề bộ phạm vi mặc định operator thông thường khi header vắng mặt
  • chỉ mất ngữ nghĩa owner khi caller thu hẹp phạm vi rõ ràng và bỏ qua operator.admin

​

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

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

• x-openclaw-model: <provider/model-or-bare-id> ghi đè mô hình backend cho agent đã chọn.
• x-openclaw-agent-id: <agentId> vẫn được hỗ trợ như một ghi đè tương thích.
• x-openclaw-session-key: <sessionKey> kiểm soát hoàn toàn định tuyến phiên.
• x-openclaw-message-channel: <channel> đặt ngữ cảnh kênh ngõ vào 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 các 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ề agent-native hơn ngày càng ưu tiên /v1/responses.

​

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

​

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"
• lượt theo dõi 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 đó

​

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

• tools không phải mảng
• 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
• tool_choice: "required" (chưa được thực thi tại runtime; sẽ được hỗ trợ sau khi thực thi cứng được triển khai)
• tool_choice: { "type": "function", "function": { "name": "..." } } (cùng lý do như required)
• các giá trị tool_choice.function.name không khớp với tools đã cung cấp

​

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

• choices[0].finish_reason = "tool_calls"
• các mục 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 đoạn delta.tool_calls mang danh tính công cụ và các mảnh đối số
• đoạn cuối cùng với finish_reason: "tool_calls"
• data: [DONE]

​

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

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

​

Thiết lập nhanh Open WebUI

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

• GET /v1/models nên liệt kê openclaw/default
• Open WebUI nên dùng openclaw/default làm id mô hình chat
• Nếu bạn muốn một provider/mô hình backend cụ thể cho agent đó, hãy đặt mô hình mặc định bình thường của agent hoặc gửi x-openclaw-model

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",
    "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 đích agent OpenClaw, không phải catalog provider thô.
• openclaw/default luôn có mặt để một id ổn định hoạt động trên nhiều môi trường.
• Các ghi đè provider/mô hình backend nằm trong x-openclaw-model, không phải trường model của OpenAI.
• /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
• OpenAI