Kết nối OpenClaw skill với các API bên ngoài

Vấn đề 7,1%

🔄 Tóm tắt nhanh: Trong bài học trước, bạn đã học về mở rộng shell - chạy các lệnh để chèn dữ liệu trực tiếp vào skill của bạn. Bây giờ, chúng ta sẽ kết nối với các dịch vụ bên ngoài. Và đây là nơi mà hầu hết người tạo skill mắc phải sai lầm bảo mật nghiêm trọng đầu tiên.

Nghiên cứu của Snyk cho thấy 283 skill trên ClawHub - chiếm 7,1% thị trường - đã làm rò rỉ API key và thông tin nhận dạng cá nhân trực tiếp trong các file SKILL.md hoặc code được đóng gói. The Register đã xác nhận rằng các skill chứa "API key được lưu trữ dưới dạng plain text trong cấu hình skill".

Đây không phải là những skill độc hại. Chúng được tạo ra bởi những người tạo có thiện chí, những người đã hardcode thông tin đăng nhập của họ để thuận tiện. Kết quả là bất kỳ ai tải xuống skill đều nhận được API key của người tạo.

Sau khi hoàn thành bài học này, bạn sẽ có thể:

• Kết nối các skill với API bên ngoài mà không cần tiết lộ thông tin đăng nhập
• Chọn phương thức xác thực phù hợp với trường hợp sử dụng của bạn

Những nguyên tắc cơ bản về bảo mật API trong skill

Trước khi viết bất kỳ code nào, hãy ghi nhớ 4 quy tắc sau:

Quy tắc 1: Không bao giờ đặt thông tin đăng nhập trong SKILL.md. Không phải trong phần đầu, không phải trong hướng dẫn, không phải trong phần bình luận, cũng không phải "tạm thời".

Quy tắc 2: Không bao giờ đặt thông tin đăng nhập trong các file được đóng gói. Không phải trong script, không phải trong file cấu hình, không phải trong asset. Nếu nó nằm trong thư mục skill, hãy giả định rằng nó sẽ được chia sẻ.

Quy tắc 3: Sử dụng biến môi trường. Lưu trữ thông tin đăng nhập trong các file .env được loại trừ khỏi kiểm soát phiên bản thông qua .gitignore.

Quy tắc 4: Ưu tiên các token có thời hạn ngắn. OAuth token hết hạn trong vòng một giờ an toàn hơn nhiều so với API key tồn tại vĩnh viễn.

✅ Kiểm tra nhanh: Bạn đang xây dựng một skill cần token truy cập cá nhân của GitHub. Bạn lưu trữ nó ở đâu?

Đáp án: Trong một biến môi trường như GITHUB_TOKEN được định nghĩa trong file .env. file .env nên nằm trong .gitignore. Skill tham chiếu đến $GITHUB_TOKEN nhưng không bao giờ chứa giá trị thực tế.

Mẫu 1: Tham chiếu biến môi trường

Mẫu đơn giản và phổ biến nhất. Skill của bạn tham chiếu các biến môi trường, và người dùng thiết lập chúng cục bộ.

Trong SKILL.md:

# Skill thông tin thời tiết

Lấy dự báo thời tiết bằng API OpenWeatherMap.

## Thiết lập
Người dùng phải thiết lập các biến môi trường sau:
- WEATHER_API_KEY — API key OpenWeatherMap
- WEATHER_CITY — Thành phố mặc định (ví dụ: "New York")

## Hướng dẫn
Sử dụng API thời tiết để lấy dự báo 3 ngày:
- Endpoint: https://api.openweathermap.org/data/2.5/forecast
- Xác thực: Truyền API key dưới dạng tham số truy vấn 'appid'
- Bao gồm nhiệt độ, điều kiện và xác suất mưa

Trong file .env của người dùng (KHÔNG phải trong thư mục skill):

WEATHER_API_KEY=abc123def456
WEATHER_CITY=San Francisco

Skill này hướng dẫn agent cách sử dụng API. Thông tin xác thực nằm trong môi trường của người dùng, không bao giờ được ghi vào các file skill.

Mẫu 2: Gọi API dựa trên script

Đối với các tương tác API phức tạp, hãy đóng gói một script xử lý những phần rắc rối:

project-stats/
├── SKILL.md
└── scripts/
    └── fetch_stats.py

SKILL.md:

# Thống kê dự án

Khi người dùng yêu cầu thống kê dự án, hãy chạy script fetch:

!python scripts/fetch_stats.py

Trình bày kết quả trong một bảng tóm tắt rõ ràng.

scripts/fetch_stats.py:

import os
import json
import urllib.request

api_key = os.environ.get("GITHUB_TOKEN")
if not api_key:
      print("ERROR: GITHUB_TOKEN not set. Run: export GITHUB_TOKEN=your_token")
      exit(1)

repo = os.environ.get("GITHUB_REPO", "owner/repo")
url = f"https://api.github.com/repos/{repo}"

req = urllib.request.Request(url, headers={
      "Authorization": f"Bearer {api_key}",
      "Accept": "application/vnd.github.v3+json"
})

with urllib.request.urlopen(req) as response:
     data = json.loads(response.read())
    print(f"Stars: {data['stargazers_count']}")
    print(f"Forks: {data['forks_count']}")
    print(f"Open Issues: {data['open_issues_count']}")

Script này đọc thông tin đăng nhập từ các biến môi trường, thực hiện gọi API và xuất ra dữ liệu sạch. Người dùng chỉ thấy kết quả đầu ra - không bao giờ thấy thông tin đăng nhập.

Mẫu 3: Tích hợp máy chủ MCP

Đối với các kết nối dịch vụ liên tục, máy chủ MCP (Model Context Protocol) xử lý xác thực và cung cấp những công cụ mà agent có thể gọi:

# Jira Task Manager

Skill này sử dụng máy chủ Jira MCP để quản lý tác vụ.

## Điều kiện tiên quyết
- Máy chủ Jira MCP phải được cấu hình và đang hoạt động
- Không cần thêm thông tin đăng nhập nào khác cho skill này

## Hướng dẫn
Khi người dùng hỏi về nhiệm vụ hoặc sự cố:
1. Sử dụng công cụ Jira MCP để tìm kiếm các sự cố phù hợp
2. Định dạng kết quả dưới dạng bảng với: Key, Summary, Status, Assignee
3. Đối với các yêu cầu tạo mới, hãy sử dụng công cụ create_issue của Jira MCP

Với MCP, lớp xác thực được tách biệt khỏi skill. Skill chỉ nói "sử dụng công cụ Jira" - cách công cụ đó xác thực được xử lý bởi cấu hình máy chủ MCP.

So sánh các phương pháp xác thực

Cây quyết định:

• Chỉ sử dụng cá nhân? → Biến môi trường
• Chia sẻ với nhóm? → OAuth hoặc MCP
• Kết nối với service thường trực? → Máy chủ MCP
• Chỉ prototype? → File .env với kế hoạch xoay vòng nhanh

✅ Kiểm tra nhanh: Skill của bạn gọi một API trả phí tính phí theo từng yêu cầu. Tại sao disable-model-invocation: true lại quan trọng ở đây?

Câu trả lời: Nếu không có nó, agent có thể tự động gọi skill bất cứ khi nào nó cho rằng điều đó là cần thiết - dẫn đến phí API tăng cao. Khi flag được thiết lập, chỉ người dùng mới có thể kích hoạt nó, giúp kiểm soát chi phí.

Xử lý lỗi trong API skill

API bị lỗi. Token hết hạn. Giới hạn tỷ lệ bị vượt quá. Skill của bạn nên xử lý những lỗi này một cách khéo léo:

## Xử lý lỗi

Nếu việc gọi API thất bại:
- **401 Unauthorized:** Thông báo cho người dùng rằng API key của họ có thể đã hết hạn hoặc không hợp lệ
- **429 Rate Limited:** Chờ 60 giây và thử lại một lần. Nếu vẫn bị hạn chế, hãy thông báo cho người dùng
- **500 Server Error:** Thông báo cho người dùng rằng dịch vụ tạm thời không khả dụng
- **Network Error:** Kiểm tra xem người dùng có kết nối Internet hay không

Không bao giờ thử lại quá hai lần. Không bao giờ để lộ phản hồi lỗi thô cho người dùng
(nó có thể chứa thông tin xác thực trong tiêu đề).

Quy tắc cuối cùng này rất quan trọng: Phản hồi lỗi API thô đôi khi bao gồm tiêu đề xác thực, token yêu cầu hoặc dữ liệu nhạy cảm khác trong phần thân. Luôn hướng dẫn agent tóm tắt lỗi, không truyền chúng trực tiếp.

Những điểm chính cần ghi nhớ

• Không bao giờ hardcode thông tin xác thực - 7,1% skill của ClawHub bị rò rỉ API key theo cách này
• Sử dụng biến môi trường cho các skill cá nhân, OAuth hoặc MCP cho các skill dùng chung/sản xuất
• OAuth token hết hạn (~1 giờ), làm cho chúng an toàn hơn so với API key tĩnh
• Script xử lý sự phức tạp - đặt logic API trong scripts/, giữ cho SKILL.md tập trung vào hành vi
• Máy chủ MCP tách biệt xác thực khỏi skill - skill cho biết phải làm gì, MCP xử lý cách kết nối
• Xử lý lỗi một cách khéo léo và không bao giờ để lộ phản hồi API thô (chúng có thể chứa thông tin xác thực)