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

Documentation Index

Fetch the complete documentation index at: https://docs2.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 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 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ở cho private-ingress (gateway.auth.mode="none"): không cần header xác thực

• Khi gateway.auth.mode="token", hãy dùng gateway.auth.token (hoặc OPENCLAW_GATEWAY_TOKEN).
• Khi gateway.auth.mode="password", hãy 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 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ỗi xác thực, endpoint 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 endpoint 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 tác nhân control-plane như các hành động operator 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 endpoint này; một khi caller vượt qua xác thực Gateway tại đây, OpenClaw coi caller đó là operator 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), endpoint khôi phục các mặc định operator đầy đủ 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 tin cậy (ví dụ xác thực proxy 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 mặc định operator thông thường.
• Nếu chính sách của tác nhân mục tiêu cho phép công cụ nhạy cảm, endpoint này có thể sử dụng chúng.
• Chỉ giữ endpoint này trên loopback/tailnet/private ingress; không phơi trực tiếp ra Internet công cộng.

• gateway.auth.mode="token" hoặc "password" + Authorization: Bearer ...
  • chứng minh việc 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
  • coi các lượt chat trên endpoint này là lượt gửi của chủ sở hữu
• các chế độ HTTP mang danh tính tin cậy (ví dụ xác thực proxy tin cậy, hoặc gateway.auth.mode="none" trên private ingress)
  • xác thực một danh tính tin cậy bên ngoài hoặc ranh giới triển khai nào đó
  • tôn trọng x-openclaw-scopes khi header này có mặt
  • quay về tập phạm vi mặc định operator thông 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

​

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

• model: "openclaw" định tuyến đến tác nhân mặc định đã cấu hình.
• model: "openclaw/default" cũng định tuyến đến tác nhân mặc định đã cấu hình.
• model: "openclaw/<agentId>" định tuyến đến 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.
• 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 việc định tuyến phiên.
• x-openclaw-message-channel: <channel> đặt ngữ cảnh kênh ingress tổng hợp cho prompt và chính sách nhận biết kênh.

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

​

Bật endpoint

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

​

Tắt endpoint

{
  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.
• Ngày càng nhiều client thiên về tác nhân hơn ư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 gồm { "type": "function", "function": { ... } }
• tool_choice: "auto", "none"
• các lượt tiếp theo messages[*].role: "tool"
• messages[*].tool_call_id để gắn kết quả công cụ trở lại lời gọi công cụ trước đó
• max_completion_tokens: số; giới hạn theo từng lần gọi cho tổng số 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 đều đượ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.

​

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 hàm
• thiếu tool.function.name
• các biến thể tool_choice như allowed_tools và custom
• tool_choice: "required" (chưa được cưỡng chế tại runtime; sẽ được hỗ trợ sau khi triển khai cưỡng chế cứng)
• 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

​

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)

​

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 với finish_reason: "tool_calls"
• data: [DONE]

​

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

• thông điệp lời gọi công cụ của assistant trước đó
• 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 nhà cung cấp/mô hình backend cụ thể cho tác nhân đó, 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

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 danh mục 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.
• Ghi đè nhà cung cấp/mô hình backend thuộc về x-openclaw-model, không phải trường model của OpenAI.
• /v1/embeddings hỗ trợ input dưới dạng một chuỗi hoặc mảng chuỗi.

​

Liên quan

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