Hướng dẫn bắt đầu nhanh yycode × OpenClaw

Tình huống áp dụng

Tài liệu này chỉ giải quyết một việc: kết nối dịch vụ mô hình của OpenClaw vào yycode và hoàn tất một lần xác minh khả dụng.

Nếu bạn chưa cài Node.js, vui lòng tham khảo Hướng dẫn cài đặt môi trường Node.js trước.

1. Chuẩn bị

Trước khi bắt đầu, vui lòng xác nhận các điểm sau:

Bạn đã tạo sẵn một API Key trong bảng điều khiển yycode
Bạn biết tên mô hình thực tế cần gọi, ví dụ gpt-5.4 (danh sách hỗ trợ đầy đủ xem mô hình được hỗ trợ bên dưới)
Môi trường chạy của bạn đáp ứng yêu cầu chính thức của OpenClaw: khuyến nghị Node 24, tương thích Node 22.16+
Người dùng Windows nên ưu tiên dùng WSL2 + Ubuntu để cài đặt và chạy OpenClaw

Mô hình được hỗ trợ

Mô hình tương thích OpenAI

Tên mô hình
`gpt-5.4`
`gpt-5.2`
`gpt-5.3-codex`
`gpt-5.2-codex`
`gpt-5.1-codex-max`
`gpt-5.1-codex-mini`

Mô hình tương thích Anthropic

Tên mô hình
`claude-opus-4-6`
`claude-sonnet-4-6`
`claude-haiku-4-5-20251001`

2. Đường dẫn khuyến nghị: dùng wizard OpenClaw để kết nối

Nếu bạn chỉ muốn thông OpenClaw và yycode trước, cách tiết kiệm công nhất là chạy wizard tích hợp sẵn của OpenClaw, đợi bảng điều khiển trình duyệt phản hồi bình thường rồi tiếp tục cấu hình channel hoặc dịch vụ thường trú nền.

Bước 1: cài đặt OpenClaw

macOS / Linux / WSL2 có thể chạy trực tiếp script cài đặt chính thức:

# Cài công cụ dòng lệnh openclaw, --no-onboard nghĩa là sau khi cài chưa tự vào wizard
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

Sau khi cài xong, có thể kiểm tra lệnh có khả dụng không:

openclaw --help

Bước 2: khởi động wizard kết nối

openclaw onboard

Bước 3: chọn nhà cung cấp tùy chỉnh trong wizard

Khi wizard vào bước mô hình và xác thực, chọn Custom provider, rồi điền theo các giá trị bên dưới:

Trường	Giá trị cần điền
Loại tương thích	`Anthropic-compatible` hoặc `OpenAI-compatible`
Địa chỉ cơ sở	xem giải thích bên dưới
Tên mô hình	`claude-sonnet-4-6` hoặc `gpt-5.4` (danh sách đầy đủ xem mô hình được hỗ trợ)
Provider ID	`yycode`
API Key	API Key yycode bạn đã tạo

Giải thích cách điền địa chỉ cơ sở:

Khi chọn Anthropic-compatible, điền: https://yycode.net

Khi chọn OpenAI-compatible, cần thêm /v1 ở cuối, điền: https://yycode.net/v1

Bước 4: hoàn tất wizard và xác minh

Khi kết nối lần đầu, gateway port, bind mode và dịch vụ thường trú nền có thể giữ mặc định trước. Sau khi hoàn tất wizard, lần lượt chạy:

# Kiểm tra định dạng cấu hình có đúng không
openclaw doctor

# Xem trạng thái hiện tại và mô hình đã load
openclaw status

# Mở bảng điều khiển local, gửi một tin nhắn để xác minh có phản hồi bình thường không
openclaw dashboard

Nếu gửi tin nhắn trong bảng điều khiển và nhận được phản hồi mô hình, nghĩa là kết nối đã thành công.

3. Kết nối bằng script

Nếu bạn muốn đưa khởi tạo OpenClaw vào script, quy trình triển khai server hoặc image doanh nghiệp, khuyến nghị dùng chế độ không tương tác.

Bước 1: export API Key

# Trước tiên ghi yycode API Key vào biến môi trường
export CUSTOM_API_KEY="YOUR_yycode_API_KEY"

Bước 2: chạy lệnh kết nối không tương tác

# Kết nối không tương tác: cấu hình yycode làm nhà cung cấp tùy chỉnh
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice custom-api-key \
  --custom-base-url "https://yycode.net" \
  --custom-model-id "gpt-5.4" \
  --custom-provider-id "yycode" \
  --custom-compatibility openai \
  --secret-input-mode ref \
  --gateway-port 18789 \
  --gateway-bind loopback

Bước 3: xác nhận tên biến môi trường

Nếu bạn dùng --secret-input-mode ref, phiên bản OpenClaw hiện tại thường sẽ lưu API Key dưới dạng tham chiếu biến môi trường. Khuyến nghị dùng trực tiếp CUSTOM_API_KEY ở trên để nhất quán với tài liệu tự động hóa chính thức.

Nếu cấu hình đã được tạo, bạn cũng có thể mở ~/.openclaw/openclaw.json để kiểm tra tên biến thực tế được tham chiếu; nếu phiên bản của bạn ghi tên biến khác, hãy bổ sung biến môi trường theo cấu hình thực tế, ví dụ:

export OPENAI_API_KEY="YOUR_yycode_API_KEY"

4. Kiểm tra thủ công hoặc ghi cấu hình thủ công

Nếu không muốn chạy wizard, bạn cũng có thể trực tiếp kiểm tra hoặc chỉnh sửa ~/.openclaw/openclaw.json.

Dưới đây là một ví dụ cấu hình có thể tham khảo trực tiếp; vui lòng thay tên mô hình và biến API Key bằng giá trị thực của bạn:

{
  agents: {
    defaults: {
      // Mô hình mặc định phải viết theo định dạng "service provider ID/model name", không được chỉ viết tên mô hình
      model: { primary: "yycode/gpt-5.4" },
    },
  },
  models: {
    providers: {
      dragoncode: {
        baseUrl: "https://yycode.net",
        // Khuyến nghị tham chiếu biến môi trường để tránh viết khóa rõ vào file cấu hình
        apiKey: "${CUSTOM_API_KEY}",
        api: "openai-completions",
        models: [
          {
            // Thay bằng tên mô hình thực tế khả dụng trong bảng điều khiển yycode
            id: "gpt-5.4",
            name: "gpt-5.4",
          },
        ],
      },
    },
  },
}

Chỗ dễ viết sai nhất: mô hình mặc định phải viết thành yycode/tên mô hình, ví dụ yycode/gpt-5.4, không được chỉ viết gpt-5.4.

5. Tiêu chuẩn thành công

Nếu thỏa mãn các mục sau, về cơ bản nghĩa là kết nối đã thông:

Địa chỉ cơ sở điền là https://yycode.net
API Key vẫn hợp lệ, chưa hết hạn, chưa bị dừng, chưa hết hạn mức
Mô hình mặc định viết thành yycode/tên mô hình của bạn
openclaw doctor và openclaw status không báo lỗi cấu hình
Bảng điều khiển trình duyệt có thể gửi tin nhắn và nhận phản hồi bình thường

6. Câu hỏi thường gặp

Rõ ràng đã điền địa chỉ nhưng vẫn không kết nối được

Ưu tiên kiểm tra địa chỉ cơ sở có phải https://yycode.net không. Không thêm /

OpenClaw khởi động được nhưng khi gửi tin nhắn báo mô hình không tồn tại

Thông thường kiểm tra trước hai mục:

Tên mô hình bạn điền có đúng là tên gọi hiện đang mở của yycode không
Mô hình mặc định đã viết thành yycode/tên mô hình, thay vì chỉ viết tên mô hình chưa

Dùng lệnh script báo thiếu API Key

Thông thường là biến môi trường chưa thực sự export thành công, hoặc tên biến không khớp với tham chiếu trong cấu hình OpenClaw.

Có thể mở trực tiếp ~/.openclaw/openclaw.json, xác nhận trường apiKey đang tham chiếu biến môi trường nào, rồi bổ sung biến tương ứng trong shell hiện tại. Theo đường dẫn khuyến nghị của tài liệu này, ưu tiên kiểm tra CUSTOM_API_KEY.

Tôi đã cấu hình xong OpenClaw, vì sao vẫn chưa dùng được trong WhatsApp hoặc Telegram?

Thông thường đây không phải vấn đề kết nối mô hình, mà là channel chưa được cấu hình xong. Trang này chỉ phụ trách thông đường gọi mô hình giữa OpenClaw và Dragon Code; cấu hình channel vui lòng tiếp tục tham khảo tài liệu Channels chính thức OpenClaw.

7. Bước tiếp theo

Chưa tạo Key: quay lại bảng điều khiển yycode để tạo API Key trước
Muốn cấu hình công cụ phát triển khác trước: tiếp tục xem Hướng dẫn bắt đầu nhanh Claude Code và Hướng dẫn bắt đầu nhanh Codex
Cần cài môi trường chạy: xem Hướng dẫn cài đặt môi trường Node.js
Gặp vấn đề kết nối thường gặp: xem Câu hỏi thường gặp