Sử dụng OpenClaw với CometAPI

Sử dụng hướng dẫn này để kết nối OpenClaw với CometAPI. Hãy chọn một định dạng API và mã mô hình cho cấu hình đầu tiên.

OpenClaw v2026.8.1 cũng có thương hiệu là OpenClaw 2.0. Gói này không sử dụng 2.x số phiên bản. Xem thông báo về OpenClaw 2.0 và ghi chú phát hành v2026.8.1.

Tài liệu tham khảo chính thức của OpenClaw:

Điều kiện tiên quyết

Node.js 22.22.3+, 24.15+ hoặc 25.9+. Khuyến nghị dùng Node 26. Node 23 không được hỗ trợ.
Tài khoản CometAPI có API key đang hoạt động từ bảng điều khiển.
Mã mô hình từ trang CometAPI Models.

Cài đặt và nâng cấp

Cài đặt lần đầu
Nâng cấp bản cài đặt

Trình cài đặt chính thức có thể cài đặt CLI mà không khởi động quy trình thiết lập ban đầu. Điều này giúp tách cấu hình mô hình thành một bước riêng.

macOS / Linux / WSL2
Windows PowerShell

Lệnh sau chạy trình cài đặt chính thức:

curl -fsSL https://openclaw.ai/install.sh \
  | bash -s -- --no-onboard

Lệnh sau chạy trình cài đặt PowerShell chính thức:

& ([scriptblock]::Create(
  (iwr -useb https://openclaw.ai/install.ps1)
)) -NoOnboard

Nếu bạn tự quản lý Node.js và npm, npm 11.16+ và npm 12 chấp nhận --allow-scripts tùy chọn này. Lệnh sau cài đặt OpenClaw mà không khởi động quy trình thiết lập ban đầu:

npm install -g openclaw@latest --allow-scripts=openclaw

Trên npm 11.15 trở xuống, hãy bỏ --allow-scripts=openclaw vì phiên bản npm đó không nhận diện tùy chọn này.Xác nhận rằng CLI đã cài đặt đáp ứng phiên bản tối thiểu cho hướng dẫn này:

openclaw --version

Tiếp tục đến Cấu hình CometAPI. Không chạy riêng quy trình thiết lập ban đầu trước, vì luồng có hướng dẫn không hiển thị mọi API tùy chỉnh adapter.

Tạo và xác minh bản sao lưu trước một bản cập nhật lớn. Tệp lưu trữ có thể chứa API key, trạng thái kênh và dữ liệu xác thực, vì vậy hãy bảo vệ tệp như cách bạn bảo vệ thư mục trạng thái OpenClaw.Các lệnh sau tạo bản sao lưu và cập nhật OpenClaw:

mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify
openclaw update

Sau khi cập nhật, sửa các quá trình di chuyển được hỗ trợ và kiểm tra tình trạng Gateway:

openclaw doctor --fix
openclaw gateway restart
openclaw health

Một bản cập nhật sẽ giữ nguyên tuyến mô hình đã cấu hình. Không lặp lại quy trình thiết lập ban đầu trừ khi bạn muốn thay đổi nhà cung cấp mô hình hoặc cơ chế xác thực của nhà cung cấp đó.

Cấu hình CometAPI

Sử dụng quy trình thiết lập cổ điển

Quy trình thiết lập cổ điển là phương thức ưu tiên cho lần cài đặt đầu tiên đối với Chat Completions, Responses và Anthropic Messages. Lệnh sau sẽ mở quy trình thiết lập cổ điển và cài đặt dịch vụ nền:

openclaw onboard --classic --install-daemon

Trong Model/Auth, hãy chọn Nhà cung cấp tùy chỉnh. Sau đó, nhập các giá trị cho một trong các tùy chọn tương thích sau:

Định dạng API	ID nhà cung cấp	Tùy chọn tương thích	Base URL
Chat Completions	`cometapi-openai`	Tương thích OpenAI	`https://api.cometapi.com/v1`
Responses	`cometapi-openai-responses`	Tương thích OpenAI Responses	`https://api.cometapi.com/v1`
Anthropic Messages	`cometapi-claude`	Tương thích Anthropic	`https://api.cometapi.com`

Nhập ID nhà cung cấp tương ứng, your-model-id và khóa API CometAPI của bạn khi được nhắc. Trình hướng dẫn trong terminal sẽ che nội dung nhập khóa API. Menu Nhà cung cấp tùy chỉnh cổ điển không bao gồm bộ điều hợp Google Generative AI . Để sử dụng bộ điều hợp đó, hãy hoàn tất Cấu hình một nhà cung cấp bằng các lệnh cấu hình, đặt mô hình chính, rồi chạy quy trình thiết lập cổ điển. Chọn Giữ nguyên cấu hình mô hình khi trình hướng dẫn hiển thị tùy chọn đó.

Cấu hình một nhà cung cấp bằng các lệnh cấu hình

Sử dụng phương thức này cho bộ điều hợp Google hoặc cho các thay đổi cấu hình có kiểm soát. OpenClaw hỗ trợ JSON5, vì vậy không phân tích cú pháp và ghi lại openclaw.json bằng một công cụ JSON nghiêm ngặt.

Trình ghi cấu hình gốc của OpenClaw xác thực JSON5 nhưng chuẩn hóa tệp thành JSON khi ghi. Các nhận xét, dấu phẩy ở cuối và định dạng hiện có có thể bị xóa. Hãy tạo bản sao lưu đã xác minh trước khi áp dụng bản vá nếu các chi tiết đó quan trọng với bạn.

Trước tiên, in đường dẫn cấu hình đang hoạt động và xác thực nội dung của nó:

openclaw config file
openclaw config validate

OpenClaw đọc khóa API của nhà cung cấp từ môi trường tiến trình hoặc tệp trạng thái toàn cục .env. Nó không tin cậy tệp .env trong không gian làm việc đối với khóa API của nhà cung cấp . Tệp toàn cục là ~/.openclaw/.env, hoặc $OPENCLAW_STATE_DIR/.env khi OPENCLAW_STATE_DIR được đặt. Nếu quy trình thiết lập cổ điển đã lưu khóa API, hãy bỏ qua bước sau. Nếu không, hãy dùng thẻ dành cho hệ điều hành của bạn để lưu khóa API mà không hiển thị khóa đó.

macOS / Linux / WSL2
Windows PowerShell

Các lệnh sau cập nhật COMETAPI_KEY một cách nguyên tử và từ chối giá trị trống:

state_dir="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
install -d -m 700 "$state_dir"
read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
if [ -z "$COMETAPI_KEY" ]; then
  echo "The CometAPI API key cannot be empty." >&2
  unset COMETAPI_KEY
  exit 1
fi
umask 077
env_file="$state_dir/.env"
temp_file="$(mktemp "${env_file}.XXXXXX")"
if [ -f "$env_file" ]; then
  awk -F= '$1 != "COMETAPI_KEY"' "$env_file" > "$temp_file"
fi
printf 'COMETAPI_KEY=%s\n' "$COMETAPI_KEY" >> "$temp_file"
chmod 600 "$temp_file"
mv "$temp_file" "$env_file"
unset COMETAPI_KEY temp_file env_file state_dir

Các lệnh sau cập nhật COMETAPI_KEY mà không hiển thị khóa này:

$stateDir = if ($env:OPENCLAW_STATE_DIR) {
  $env:OPENCLAW_STATE_DIR
} else {
  Join-Path $HOME ".openclaw"
}
New-Item -ItemType Directory -Force -Path $stateDir | Out-Null
$secureKey = Read-Host "CometAPI API key" -AsSecureString
$plainKey = [Net.NetworkCredential]::new("", $secureKey).Password
if ([string]::IsNullOrWhiteSpace($plainKey)) {
  throw "The CometAPI API key cannot be empty."
}
$envFile = Join-Path $stateDir ".env"
$lines = @()
if (Test-Path $envFile) {
  $lines = @(Get-Content $envFile | Where-Object {
    $_ -notmatch '^COMETAPI_KEY='
  })
}
$lines += "COMETAPI_KEY=$plainKey"
$tempFile = Join-Path $stateDir ".$([guid]::NewGuid()).tmp"
[IO.File]::WriteAllLines($tempFile, $lines)
Move-Item -Force $tempFile $envFile
$plainKey = $null
$secureKey = $null

Trước khi thêm một nhà cung cấp, hãy kiểm tra đường dẫn đích của nó. Thay thế ID nhà cung cấp trong lệnh sau bằng ID từ thẻ bạn đã chọn:

openclaw config get models.providers.cometapi-openai --json

Nếu lệnh trả về một nhà cung cấp đã được cấu hình, hãy dừng lại trước khi áp dụng ví dụ. config patch hợp nhất các đối tượng, nhưng thay thế các mảng. Hãy hợp nhất mô hình mới vào mảng mô hình của nhà cung cấp trước khi ghi mảng đó. Việc này giữ lại siêu dữ liệu mô hình, header tùy chỉnh và các cài đặt nhà cung cấp khác. Chọn một định dạng API. Mỗi bản vá sử dụng SecretRef dựa trên môi trường, thay đổi chỉ các đường dẫn cấu hình đích và giữ nguyên các phần cấu hình khác.

ID mô hình không tự động tương thích với mọi bộ điều hợp API. Hãy chọn một bộ điều hợp mà mô hình và tuyến CometAPI cụ thể hỗ trợ, rồi xác minh tổ hợp nhà cung cấp/mô hình/bộ điều hợp đó bằng một yêu cầu trực tiếp. Giá trị your-model-id bên dưới là chỗ dành sẵn cho cấu hình, không phải là một tuyên bố về khả năng tương thích phổ quát.

Chat Completions
Responses
Anthropic Messages
Google Generative AI

ID nhà cung cấp: cometapi-openai
Bộ điều hợp OpenClaw: openai-completions
Base URL: https://api.cometapi.com/v1
Tham chiếu mô hình chính: cometapi-openai/your-model-id

Tạo cometapi.patch.json5 với bản vá nhà cung cấp này:

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-openai": {
        baseUrl: "https://api.cometapi.com/v1",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "openai-completions",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

Xác thực bản vá trước khi OpenClaw ghi cấu hình:

openclaw config patch --file ./cometapi.patch.json5 --dry-run

Nếu xác thực thành công, hãy áp dụng cùng bản vá:

openclaw config patch --file ./cometapi.patch.json5

Nếu chưa cấu hình mô hình chính, hãy đặt mô hình này làm mặc định:

openclaw models set cometapi-openai/your-model-id

Xác minh cấu hình nhà cung cấp và gửi một yêu cầu mô hình tối thiểu:

openclaw models list --provider cometapi-openai
openclaw models status --probe \
  --probe-provider cometapi-openai
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-openai/your-model-id \
  --thinking off \
  --json

Để chuyển phiên trò chuyện OpenClaw đang hoạt động, hãy chạy lệnh trò chuyện này:

/model cometapi-openai/your-model-id

ID nhà cung cấp: cometapi-openai-responses
Bộ điều hợp OpenClaw: openai-responses
Base URL: https://api.cometapi.com/v1
Tham chiếu mô hình chính: cometapi-openai-responses/your-model-id

Tạo cometapi.patch.json5 với bản vá nhà cung cấp này:

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-openai-responses": {
        baseUrl: "https://api.cometapi.com/v1",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "openai-responses",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

Xác thực bản vá trước khi OpenClaw ghi cấu hình:

openclaw config patch --file ./cometapi.patch.json5 --dry-run

Nếu xác thực thành công, hãy áp dụng cùng bản vá:

openclaw config patch --file ./cometapi.patch.json5

Nếu chưa cấu hình mô hình chính, hãy đặt mô hình này làm mặc định:

openclaw models set cometapi-openai-responses/your-model-id

Xác minh cấu hình nhà cung cấp và gửi một yêu cầu mô hình tối thiểu:

openclaw models list --provider cometapi-openai-responses
openclaw models status --probe \
  --probe-provider cometapi-openai-responses
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-openai-responses/your-model-id \
  --thinking off \
  --json

Để chuyển phiên trò chuyện OpenClaw đang hoạt động, hãy chạy lệnh trò chuyện này:

/model cometapi-openai-responses/your-model-id

ID nhà cung cấp: cometapi-claude
Bộ điều hợp OpenClaw: anthropic-messages
Base URL: https://api.cometapi.com
Tham chiếu mô hình chính: cometapi-claude/your-model-id

Tạo cometapi.patch.json5 với bản vá nhà cung cấp này:

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-claude": {
        baseUrl: "https://api.cometapi.com",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "anthropic-messages",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

Xác thực bản vá trước khi OpenClaw ghi cấu hình:

openclaw config patch --file ./cometapi.patch.json5 --dry-run

Nếu xác thực thành công, hãy áp dụng cùng bản vá:

openclaw config patch --file ./cometapi.patch.json5

Nếu chưa cấu hình mô hình chính, hãy đặt mô hình này làm mặc định:

openclaw models set cometapi-claude/your-model-id

Xác minh cấu hình nhà cung cấp và gửi một yêu cầu mô hình tối thiểu:

openclaw models list --provider cometapi-claude
openclaw models status --probe \
  --probe-provider cometapi-claude
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-claude/your-model-id \
  --thinking off \
  --json

Để chuyển phiên trò chuyện OpenClaw đang hoạt động, hãy chạy lệnh trò chuyện này:

/model cometapi-claude/your-model-id

ID nhà cung cấp: cometapi-google
Bộ điều hợp OpenClaw: google-generative-ai
Base URL: https://api.cometapi.com/v1beta
Tham chiếu mô hình chính: cometapi-google/your-model-id

Tạo cometapi.patch.json5 với bản vá nhà cung cấp này:

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-google": {
        baseUrl: "https://api.cometapi.com/v1beta",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "google-generative-ai",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

Xác thực bản vá trước khi OpenClaw ghi cấu hình:

openclaw config patch --file ./cometapi.patch.json5 --dry-run

Nếu xác thực thành công, hãy áp dụng cùng bản vá:

openclaw config patch --file ./cometapi.patch.json5

Nếu chưa cấu hình mô hình chính, hãy đặt mô hình này làm mặc định:

openclaw models set cometapi-google/your-model-id

Xác minh cấu hình nhà cung cấp và gửi một yêu cầu mô hình tối thiểu:

openclaw models list --provider cometapi-google
openclaw models status --probe \
  --probe-provider cometapi-google
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-google/your-model-id \
  --thinking off \
  --json

Để chuyển phiên trò chuyện OpenClaw đang hoạt động, hãy chạy lệnh trò chuyện này:

/model cometapi-google/your-model-id

Nếu một cấu hình đã sử dụng ID nhà cung cấp cometapi-gemini, hãy giữ nguyên ID đó và dùng nó trong tham chiếu mô hình cũng như các lệnh. Không đổi tên ID đó hoặc tạo nhà cung cấp trùng lặp chỉ để khớp với hướng dẫn này.

Danh sách mô hình OpenClaw 2026.8.1 với bốn định dạng nhà cung cấp CometAPI

Đối với nhà cung cấp mới, openclaw config set cung cấp cùng lược đồ và các bước kiểm tra SecretRef. Dùng --strict-json, --merge và --dry-run trước khi ghi. Phương án thay thế sau xem trước nhà cung cấp Chat Completions: ghi. Phương án thay thế sau xem trước nhà cung cấp Chat Completions:

openclaw config set models.providers.cometapi-openai \
  '{
    "baseUrl": "https://api.cometapi.com/v1",
    "apiKey": {
      "source": "env",
      "provider": "default",
      "id": "COMETAPI_KEY"
    },
    "api": "openai-completions",
    "models": [
      {
        "id": "your-model-id",
        "name": "CometAPI model",
        "input": ["text"]
      }
    ]
  }' \
  --strict-json --merge --dry-run

Nếu chạy thử thành công, hãy lặp lại lệnh mà không có --dry-run để lưu. Không áp dụng ví dụ này cho nhà cung cấp đã được cấu hình. Mảng models phải bao gồm toàn bộ danh sách mô hình đã hợp nhất của nhà cung cấp trước khi ghi.

Tìm hiểu siêu dữ liệu mô hình

Các bản vá tối thiểu khai báo một mô hình chỉ có văn bản. Chỉ thêm siêu dữ liệu tùy chọn khi bạn đã xác minh thông số kỹ thuật của mô hình:

Trường	Tác động
`input`	Khai báo các phương thức đầu vào được chấp nhận. Chỉ dùng `["text", "image"]` khi mô hình chấp nhận đầu vào hình ảnh gốc.
`contextWindow`	Ghi lại dung lượng Context Window gốc của mô hình.
`contextTokens`	Giới hạn ngân sách đầu vào đang hoạt động mà không thay đổi `contextWindow`.
`maxTokens`	Giới hạn Tokens đầu ra mà OpenClaw yêu cầu từ mô hình.

Các giá trị không chính xác có thể ẩn đầu vào được hỗ trợ, phóng đại ngữ cảnh có thể sử dụng hoặc yêu cầu kích thước đầu ra không được hỗ trợ. Giữ your-model-id trong các ví dụ có thể tái sử dụng, và dùng trang Models của CometAPI để chọn ID mô hình.

Xác minh toàn bộ thiết lập

Sau khi thay đổi tệp cấu hình hoặc tệp .env toàn cục, hãy khởi động lại Gateway:

openclaw gateway restart

Sau đó, xác thực cấu hình và trạng thái Gateway:

openclaw config validate
openclaw doctor
openclaw health

Chạy các lệnh dành riêng cho nhà cung cấp từ thẻ định dạng API đã chọn. Danh sách mô hình hoặc kiểm tra trạng thái chỉ xác nhận cấu hình. Lệnh openclaw agent exec gửi một yêu cầu mô hình thực. Xác nhận rằng lệnh trả về OPENCLAW_OK mà không có lỗi xác thực, adapter hoặc mô hình chưa được giải quyết. Nếu OpenClaw thử lại một yêu cầu, hãy ghi lại và kiểm tra từng lần thử thay vì coi dấu hiệu cuối cùng là thành công trong một lần thử duy nhất.

Khắc phục sự cố

Thiếu API key

Xác nhận rằng COMETAPI_KEY có trong môi trường quy trình hoặc tệp trạng thái toàn cục .env. Không in giá trị ra đầu ra terminal.Sau khi sửa nguồn key đáng tin cậy, hãy khởi động lại và kiểm tra Gateway:

openclaw gateway restart
openclaw health

Một ID nhà cung cấp có các thiết lập khác

Không ghi đè nhà cung cấp có baseUrl, api, tiêu đề tùy chỉnh hoặc siêu dữ liệu mô hình khác. Trước tiên, hãy kiểm tra nhà cung cấp đích:

openclaw config get models.providers.cometapi-openai --json
openclaw config validate

Sử dụng một ID nhà cung cấp khác khi cả hai cấu hình đều có chủ đích. Nếu sự khác biệt là ngoài ý muốn, hãy tạo một bản sao lưu đã xác minh trước khi thay đổi nhà cung cấp đích.

Một bản cập nhật chưa hoàn tất

Kiểm tra trạng thái cập nhật trước khi sửa chữa bản cài đặt:

openclaw update status --json
openclaw update repair
openclaw doctor --fix
openclaw health

Các lệnh này giữ nguyên thư mục trạng thái.

Cần hoàn tác mã

Cài đặt lại một phiên bản package đã biết trong khi vẫn giữ thư mục trạng thái. Trước tiên, hãy xem trước thao tác:

openclaw update --tag 2026.8.1 --dry-run

Nếu bản xem trước chính xác, hãy chạy cùng thao tác mà không có --dry-run:

openclaw update --tag 2026.8.1
openclaw doctor --fix
openclaw health

Chỉ khôi phục bản sao lưu trạng thái khi mã đã cài đặt không thể đọc trạng thái. Việc khôi phục trạng thái có thể loại bỏ các phiên và thay đổi cấu hình đã được tạo sau thời điểm sao lưu.

Tổng quan

Tác nhân lập trình AI

Tác nhân AI

Ứng dụng chat AI

Dịch thuật và ngôn ngữ

Nền tảng tự động hóa

Quan sát và đánh giá

Framework AI

Điều kiện tiên quyết

Cài đặt và nâng cấp

Cấu hình CometAPI

Sử dụng quy trình thiết lập cổ điển

Cấu hình một nhà cung cấp bằng các lệnh cấu hình

Tìm hiểu siêu dữ liệu mô hình

Xác minh toàn bộ thiết lập

Khắc phục sự cố

​Điều kiện tiên quyết

​Cài đặt và nâng cấp

​Cấu hình CometAPI

​Sử dụng quy trình thiết lập cổ điển

​Cấu hình một nhà cung cấp bằng các lệnh cấu hình

​Tìm hiểu siêu dữ liệu mô hình

​Xác minh toàn bộ thiết lập

​Khắc phục sự cố

Điều kiện tiên quyết

Cài đặt và nâng cấp

Cấu hình CometAPI

Sử dụng quy trình thiết lập cổ điển

Cấu hình một nhà cung cấp bằng các lệnh cấu hình

Tìm hiểu siêu dữ liệu mô hình

Xác minh toàn bộ thiết lập

Khắc phục sự cố