> ## 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/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>