> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentwallex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 最佳實踐

> 安全提示、策略設定、監控建議和正式環境就緒檢查清單。

## 安全性

<Warning>
  切勿在用戶端程式碼、公開儲存庫或應用程式日誌中暴露 API 金鑰。
</Warning>

* **將 API 金鑰儲存在密鑰管理工具中** — 使用 AWS Secrets Manager、HashiCorp Vault 或您平台的密鑰解決方案。避免在正式環境中使用 `.env` 檔案。
* **每 90 天輪換金鑰** — 設定定期提醒。請參閱 [API 金鑰](/zh-Hant/introduction/api-keys)了解輪換說明。
* **每個環境使用獨立金鑰** — 切勿在開發、預備和正式環境之間共用金鑰。
* **啟用 IP 白名單** — Growth 和 Enterprise 方案可將 API 存取限制於已知的伺服器 IP。
* **使用沙箱進行測試** — 切勿使用正式環境金鑰或真實資金進行測試。

## 策略配置

<Tip>
  從最嚴格的策略開始，隨著您對代理行為的信心增加而逐步放寬。
</Tip>

### 建議的初始策略

```typescript theme={null}
await aw.policies.update("agent_abc123", {
  // Start with low limits
  maxTransactionAmount: "100",
  dailyLimit: "1000",
  monthlyLimit: "10000",

  // Whitelist trusted addresses only
  allowedAddresses: ["0xTrustedVendor1", "0xTrustedVendor2"],

  // Restrict to stablecoins
  allowedTokens: ["USDC"],

  // Prevent runaway loops
  velocityLimit: {
    maxCount: 50,
    windowSeconds: 3600,
  },

  // Human review for larger amounts
  requireHumanApproval: true,
  humanApprovalThreshold: "500",
});
```

### 策略建議

* **使用 allowedAddresses** — 白名單比黑名單更安全。
* **設定速率限制** — 防止代理進入無限交易迴圈。
* **啟用人工審核** — 針對超過有意義門檻的金額。
* **每週檢視** — 隨著代理行為模式的明確，調整策略。
* **使用範本** — 為常見配置建立可重複使用的範本。

## 監控

### 訂閱關鍵事件

```typescript theme={null}
await aw.webhooks.create({
  url: "https://your-app.com/webhooks",
  events: [
    "payment.completed",
    "payment.failed",
    "policy.violated",
    "agent.frozen",
  ],
});
```

### 監控項目

| 指標           | 原因              |
| ------------ | --------------- |
| 策略違規         | 表示代理配置有誤或出現意外行為 |
| 失敗的交易        | 可能表示資金不足或區塊鏈問題  |
| 凍結事件         | 由異常偵測或手動操作觸發    |
| 每個代理的每日支出    | 及早發現預算超支        |
| API 錯誤率      | 偵測整合問題          |
| Webhook 傳送失敗 | 確保您的處理程式健康運作    |

### 稽核日誌

定期檢視稽核日誌以發現意外活動：

```bash theme={null}
curl -X GET "https://api.agentwallex.com/api/v1/audit-logs?page_num=1&page_size=50" \
  -H "X-API-Key: awx_your_api_key"
```

## 正式環境就緒檢查清單

上線前請使用此檢查清單：

* [ ] **API 金鑰** — 已建立正式環境金鑰並儲存在密鑰管理工具中
* [ ] **環境** — SDK 已使用 `environment: "production"` 初始化
* [ ] **策略已配置** — 每個代理的支出限額、地址白名單和速率控制
* [ ] **人工審核** — 已為高價值交易啟用並設定適當的門檻
* [ ] **Webhooks 已註冊** — 已為 `payment.completed`、`payment.failed` 和 `policy.violated` 部署處理程式
* [ ] **Webhook 簽名已驗證** — 處理程式在每次傳送時驗證 `X-AgentWallex-Signature`
* [ ] **錯誤處理** — 已捕獲並記錄 SDK 錯誤，對暫時性故障有重試邏輯
* [ ] **監控** — 已設定策略違規、失敗交易和凍結事件的警報
* [ ] **稽核日誌存取** — 團隊成員可在儀表板中檢視稽核日誌
* [ ] **緊急程序** — 已記錄如何凍結代理以及誰有權限
* [ ] **金鑰輪換排程** — 已設定 90 天金鑰輪換的日曆提醒
* [ ] **沙箱測試** — 所有流程在切換到正式環境前已在測試網上端對端測試完成
* [ ] **錢包注資** — 正式環境錢包已注入足夠餘額以應對預期交易量
* [ ] **速率限制已了解** — 應用程式使用指數退避處理 429 回應

<Info>
  AgentWallex 團隊可在您上線前檢視您的整合。請聯繫 [support@agentwallex.com](mailto:support@agentwallex.com) 進行上線前審查。
</Info>