跳到主要内容

最佳实践

本文总结使用 OpenClaw 时的推荐做法，涵盖配置设计、安全与隐私、多 Agent 路由、通信与可靠性、运维与监控以及升级与兼容，帮助你在生产或长期使用中更稳定、可控。

配置设计最佳实践​

1. 配置与代码分离​

  • 非敏感配置（如路由规则、模型名称、端口、Agent 名称）可纳入版本控制，便于回溯与协作。
  • 敏感信息（API Key、Token、Secret）仅通过环境变量或加密配置注入，不写进配置文件并提交仓库。
# 示例：通过环境变量注入模型 Key（具体变量名以版本文档为准）
export OPENAI_API_KEY="sk-..."
export MINIMAX_API_KEY="..."
openclaw-cn gateway --port 18789

2. 环境区分​

  • 使用不同配置文件或环境变量前缀区分开发 / 测试 / 生产，避免误用生产 Key 或影响线上用户。
  • 例如：config.dev.yaml、config.prod.yaml，或通过 ENV=production 等变量切换加载的配置。

3. 路由规则清晰可维护​

  • 路由规则按「渠道 → 用户/群组 → Agent」设计，避免重叠或遗漏；为默认 Agent 显式配置，便于排错。
  • 为规则添加注释或命名，便于后续修改与审计。
# 路由规则示例（概念性，格式以版本文档为准）
routing:
  # 内部管理员使用内部助手
  - name: admin-internal
    match: { channel: telegram, user_id: "admin_*" }
    agent: internal-assistant
  # 客服群使用客服 Agent
  - name: support-group
    match: { channel: wechat, group_id: "support_*" }
    agent: customer-service
  # 默认使用通用 Agent
  default: default-agent

安全与隐私​

1. 密钥与凭证管理​

  • 不要将 API Key、Token 写进代码或提交到仓库。使用环境变量或加密配置，并限制访问权限。
  • 定期轮换各通道与模型的密钥；轮换后在 OpenClaw 中更新配置或环境变量，并重启网关验证。
  • 若 Key 曾泄露，立即在对应厂商控制台撤销或轮换，并评估是否产生未授权调用。

2. 配对与访问控制​

  • 私信场景下开启配对审批：只有经你确认的用户才能与 Agent 对话，避免未授权访问与滥用。
  • 重要业务使用独立 Agent 与独立配置，便于审计与权限边界清晰。

3. 网络与访问控制​

  • 网关端口尽量不直接对公网开放，或通过防火墙/安全组限制来源 IP。
  • 若通过 Nginx 等做反向代理，建议启用 HTTPS 并配置合法证书，避免中间人窃听。
  • 生产环境与测试环境分离配置与数据，避免误操作影响线上用户。

4. 安全清单（简要）​

  • 所有 Key/Token 通过环境变量或加密配置管理。
  • 私信已开启配对审批（若适用）。
  • 网关不直接暴露公网或已做访问控制与 HTTPS。
  • 生产与测试环境隔离。

多 Agent 路由​

OpenClaw 支持将不同用户或群组路由到不同 Agent，实现隔离与分工。

建议​

  • 明确路由规则：按用户 ID、群组 ID 或渠道类型划分，避免重叠或遗漏；为默认 Agent 显式指定。
  • 为每个 Agent 单独配置模型与系统提示词，避免混用导致行为混乱。
  • 重要业务使用独立 Agent 与独立配置，便于审计与回滚；可配合命名与注释便于维护。

通信与可靠性​

1. 通道连接与重连​

  • 网关通常具备通道断线重连；若自研通道适配器，需实现指数退避重连与错误上报。
  • 关注通道侧 Webhook 或长连接的超时与限频，避免因配置不当导致频繁断连。

2. 模型调用​

  • 为模型调用配置合理超时与重试（若支持），避免单次失败导致长时间阻塞。
  • 可为关键 Agent 配置备用模型或降级策略，提高可用性。

3. 日志与排错​

  • 合理设置日志级别，保留足够时长便于排查问题。
  • 不要记录敏感信息：如完整消息内容、用户 ID、Token 等；可对敏感字段脱敏或仅记录必要元数据。

配置管理​

  • 版本化配置：将非敏感配置纳入版本控制，变更时写清注释，便于回溯与协作。
  • 备份：定期备份配置文件与持久化数据（若有），以便故障恢复或迁移；备份存储需权限控制。
  • 变更流程：生产配置变更建议先在测试环境验证，再在生产执行，并保留回滚方案。

运维与监控​

1. 常驻运行​

  • 生产环境使用 systemd、supervisor 或官方推荐的守护进程方式运行网关，避免因关闭终端而退出。
  • 配置开机自启（若适用），减少宕机后恢复时间。

2. 日志与监控​

  • 集中收集网关与通道日志，便于排查连接、路由与模型调用问题。
  • 若有健康检查接口或脚本，可配合监控系统做存活探测与告警，必要时自动重启或通知。

3. 资源与容量​

  • 关注网关所在机器的 CPU、内存与网络；通道与并发增加时适当扩容或优化配置。
  • 模型 API 通常有 QPS 限制，高并发场景下注意限流与排队策略（若支持）。

升级与兼容​

  • 升级前阅读 Release Notes，关注破坏性变更与配置迁移说明。
  • 在测试环境先完成升级与验证，再在生产环境执行。
  • 保留上一版本的配置与数据备份，以便回滚；必要时可先做一次全量备份再升级。

更多细节可参考 开发指南 与 常见问题。