Cài đặt OpenClaw & Cài đặt API

OpenClaw có thể định tuyến yêu cầu mô hình qua cổng API OpenAI compatible tương thích của TokenHub. Giữ nguyên cách cài đặt chính thức, sau đó thay API key, Base URL và model ID.

Endpoint TokenHub dùng trong hướng dẫn này là https://us-api.tokenhub.com/v1/chat/completions.

Khi nào nên dùng

Bắt đầu với repository nhỏ hoặc dự án thử nghiệm. Trước tiên yêu cầu công cụ đọc file, giải thích mã hoặc lập kế hoạch, rồi mới bật chỉnh sửa.

Cài đặt hoặc mở công cụ

Làm theo tài liệu chính thức của OpenClaw để cài đặt hoặc mở công cụ. Nếu giao diện thay đổi, ưu tiên tài liệu hiện tại.

Với công cụ CLI, hãy kiểm tra executable trước khi thêm thông tin xác thực TokenHub:

openclaw --version

Chuẩn bị thông tin xác thực TokenHub

Tạo TokenHub API key và chọn một mô hình phù hợp từ danh sách mô hình TokenHub.

export TOKENHUB_API_KEY="sk-..."

Lưu key trong shell cục bộ, kho bí mật của IDE hoặc trường API key an toàn của công cụ. Không commit key vào repository.

Cấu hình nhà cung cấp TokenHub

Trong phần Models, Providers, API Keys hoặc OpenAI Compatible, nhập các giá trị dưới đây.

Giá trị provider

Use the official custom provider guide for the current models.providers schema and OpenAI-compatible adapter behavior.

Vị trí file cài đặt

Store the key where the managed Gateway can read it:

TOKENHUB_API_KEY=your-local-tokenhub-key

Add the custom provider to ~/.openclaw/openclaw.json:

{
  models: {
    mode: 'merge',
    providers: {
      tokenhub: {
        baseUrl: '__API_BASE_URL__/v1',
        apiKey: '${TOKENHUB_API_KEY}',
        api: 'openai-completions',
        models: [
          {
            id: 'gpt-4.1',
            name: 'TokenHub / gpt-4.1',
            reasoning: false,
            input: ['text'],
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: 'tokenhub/gpt-4.1',
      },
    },
  },
}

Replace the example model metadata with the actual limits and capabilities of the TokenHub model you selected. Keep the catalog id bare, then add the provider prefix only when selecting it as tokenhub/gpt-4.1.

Restart the Gateway and verify the custom provider:

openclaw gateway restart
openclaw models list --provider tokenhub
openclaw models set "tokenhub/gpt-4.1"

The API key remains in ~/.openclaw/.env so launchd, systemd, Docker, and other managed Gateway processes can read it.

Nếu công cụ tách chat, edit, apply và fast models, hãy dùng cùng một mô hình TokenHub cho lần thử đầu tiên. Sau đó mới tách theo chi phí, độ trễ và năng lực suy luận.

Biến môi trường tạm thời chỉ để debug

Chỉ dùng biến tạm thời để kiểm tra key, mạng và tên mô hình. Sau khi xác minh, chuyển cùng giá trị vào cấu hình bền vững ở trên.

export TOKENHUB_API_KEY="sk-..."

Xác minh kết nối

Trước tiên dùng prompt chỉ đọc để xác nhận mô hình đọc được ngữ cảnh và không sửa file. Sau đó mới thử chỉnh sửa hoặc tác vụ agent.

Đọc README của dự án và tóm tắt trong ba câu. Không chỉnh sửa file.

Sau khi prompt chạy thành công, kiểm tra log TokenHub để xác nhận tên mô hình, endpoint, lượng token và billing group.

Khắc phục sự cố