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

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 giao diện tương thích Anthropic của yycode vào Hermes và hoàn tất một lần xác minh khả dụng tối thiểu.

Nếu hiện tại bạn dùng Hermes, không phải OpenClaw, Cherry Studio hay client khác, thì tài liệu này chính là cách kết nối tương ứng.

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ế mà Hermes hiện cần gọi
Bạn có thể chỉnh sửa file cấu hình Hermes config.yaml
Lần này bạn muốn kết nối endpoint tương thích Anthropic của yycode, không phải endpoint tương thích OpenAI

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

Tài liệu hiện ưu tiên bao phủ kết nối mô hình tương thích Anthropic của yycode; các tên mô hình thường gặp như sau:

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

Nếu bạn không chắc mô hình nào thực tế đang khả dụng trong tài khoản, hãy lấy bảng điều khiển hoặc bản ghi gọi hiện có của bạn làm chuẩn.

3. Đường dẫn khuyến nghị: kết nối qua `custom_providers` của Hermes

Khi Hermes kết nối yycode, ý tưởng cốt lõi là:

Khai báo một yycode provider trong custom_providers
Trong khối model, trỏ mô hình mặc định tới provider này
Tắt smart_model_routing để tránh Hermes tự động chuyển sang mô hình khác

Bước 1: định nghĩa provider tùy chỉnh

custom_providers:
  - name: custom-yycode-net-aws
    base_url: https://yycode.net
    api_key: <your-key>
    api_mode: anthropic_messages
    models:
      - claude-opus-4-6

Hai điểm quan trọng nhất ở đây:

base_url viết https://yycode.net
api_mode bắt buộc viết anthropic_messages

Bước 2: trỏ mô hình mặc định tới provider này

model:
  default: claude-opus-4-6
  provider: custom-yycode-net-aws
  base_url: https://yycode.net
  api_key: <your-key>
  api_mode: anthropic_messages

provider ở đây phải khớp với name trong custom_providers phía trên, nếu không Hermes sẽ không đi vào Dragon Code provider bạn đã định nghĩa.

Bước 3: tắt Smart Model Routing

smart_model_routing:
  enabled: false

Nếu không tắt, Hermes có thể tự động chuyển sang mô hình rẻ hơn vì tin nhắn ngắn, dẫn đến việc bạn rõ ràng đã cấu hình claude-opus-4-6 nhưng thực tế chạy mô hình khác.

4. Cấu hình tối thiểu có thể dùng trực tiếp

Dưới đây là một ví dụ tối thiểu đã gộp lại. Thay <your-key> bằng Dragon Code API Key của bạn:

model:
  default: claude-opus-4-6
  provider: custom-yycode-net-aws
  base_url: https://yycode.net
  api_key: <your-key>
  api_mode: anthropic_messages

custom_providers:
  - name: custom-yycode-net-aws
    base_url: https://yycode.net
    api_key: <your-key>
    api_mode: anthropic_messages
    models:
      - claude-opus-4-6

smart_model_routing:
  enabled: false

fallback_providers:
  - provider: minimax-cn
    model: MiniMax-M2.7

Nếu muốn chuyển sang mô hình tương thích Anthropic khác, chỉ cần đổi đồng thời tên mô hình trong model.default và custom_providers[].models.

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à Hermes và Dragon Code đã kết nối:

base_url điền là https://yycode.net
api_mode điền là anthropic_messages
model.provider trỏ tới tên provider bạn định nghĩa trong custom_providers
smart_model_routing.enabled đã tắt
Sau khi Hermes gửi tin nhắn, thực tế có thể nhận phản hồi mô hình bình thường

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

Vì sao không thể kết nối theo cách tương thích OpenAI?

Lần này Hermes kết nối yycode nên đi theo định dạng message native của Anthropic, tức là /v1/messages.

Kết luận đã biết:

/v1/messages khả dụng
/v1/chat/completions không phù hợp làm đường chính cho phương án cấu hình Hermes trong tài liệu này

Vì vậy api_mode bắt buộc viết anthropic_messages, đừng cấu hình theo chế độ tương thích OpenAI.

Vì sao tôi đã chọn `claude-opus-4-6`, nhưng thực tế lại chạy mô hình khác?

Ưu tiên kiểm tra smart_model_routing.enabled đã tắt chưa.

Nếu Hermes đang bật smart routing, tin nhắn ngắn có thể bị tự động chuyển sang mô hình rẻ hơn, khiến lựa chọn trên giao diện và mô hình request thật không一致.

Có dùng được `api_key_env` không?

Dựa trên bản ghi cấu hình hiện tại, api_key_env trong Hermes v0.10.0 có tình trạng không ổn định trong khối model và custom_providers, có thể khiến biến môi trường không được expand đúng và cuối cùng trả về 401.

Nếu bạn đã xác nhận đúng là vấn đề này, có thể tạm quay về cách điền trực tiếp api_key, thông đường kết nối trước rồi quyết định có tiếp tục điều tra phương án biến môi trường hay không.

Vì sao trả về 401?

Thông thường hãy kiểm tra trước các mục sau:

API Key có hợp lệ không
api_key đã điền vào đúng vị trí mà model và custom_providers cần chưa
Hermes hiện tại có thật sự load file cấu hình bạn đã sửa không

Vì sao trả về 503 hoặc service unavailable?

Nếu cấu hình hiện tại của bạn đi theo đường tương thích OpenAI, hãy quay lại kiểm tra có phải đã cấu hình sai api_mode cho Hermes hay không.

Đường dẫn khuyến nghị trong tài liệu này là cách kết nối tương thích Anthropic, không khuyến nghị trộn với cách viết tương thích OpenAI.

7. Ví dụ xác minh API

Nếu muốn bỏ qua Hermes trước và trực tiếp xác minh endpoint Dragon Code có khả dụng không, có thể gọi endpoint native Anthropic trước:

curl -X POST "https://yycode.net/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-key>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-opus-4-6","max_tokens":50,"messages":[{"role":"user","content":"hi"}]}'

Nếu request này trả về bình thường, quay lại kiểm tra cấu hình Hermes sẽ trực tiếp hơn khi排障.

8. Bước tiếp theo

Muốn tiếp tục kết nối client khác: xem Hướng dẫn bắt đầu nhanh OpenClaw, Hướng dẫn bắt đầu nhanh Cherry Studio
Chưa tạo Key: quay lại bảng điều khiển yycode để tạo API Key trước
Muốn thống nhất sắp xếp cấu hình công cụ phát triển: tiếp tục xem các tài liệu kết nối nhanh khác trong site