开发者安全指南

July 12, 2026 · View on GitHub

理解和配置 HotPlex Gateway 的安全机制，确保 Agent 安全运行

概述

HotPlex Gateway 采用纵深防御（Defense in Depth）策略，通过七层安全机制保护系统：

网络层 → API Key + Bot ID 认证 → SSRF 防护 → 命令白名单 → 环境隔离 → Tool 控制 → 输出限制

开发者需要理解每层安全机制以正确配置和使用。本文档聚焦权限请求、Tool 访问控制和安全配置最佳实践。

权限请求（Permission Request）

何时触发

当 AI Agent 需要执行敏感操作时，Worker 通过 AEP permission_request 事件请求用户审批：

{
  "type": "permission_request",
  "data": {
    "id": "perm_123",
    "tool_name": "write_file",
    "description": "Write to /app/main.py",
    "args": ["/app/main.py", "write"]
  }
}

常见触发场景：

文件写入：write_file、edit_file
命令执行：bash
网络请求：web_fetch
系统操作：创建/删除文件、修改权限

权限模式

Workspace 级 4 档统一权限模式（#789），跨 Claude Code / Codex / OpenCode Server / ACP 四类 Worker 统一映射。空值（默认）= "Worker 默认"：bridge 注入全局 worker.default_permission_mode（r3 起缺省 workspace），再按各 Worker 映射生效。

模式	行为	适用场景
`read-only`	仅规划与只读，不执行写操作	代码审查、只读分析
`workspace`	自动接受编辑，其他敏感操作仍需审批	日常开发
`auto-edit`	全自动执行，无需逐项确认	受信任的自动化
`bypass`	跳过所有权限确认	CI/CD、沙箱环境

权限模式作为 Workspace 属性持久化，通过 WebChat Workspace 设置或 HTTP API 配置；运行时亦可用 /perm <模式> 命令临时切换。各档到 Worker 原生参数的映射见远程开发指南。

全局配置项 worker.default_permission_mode（缺省 workspace）由 bridge 在 workspace 无显式 override 时注入；workspace 级显式 override 优先级更高。运维想全局放开权限须显式设为 bypass。

交互超时

默认 5 分钟超时，超时后自动拒绝（auto-deny）。通过 InteractionManager 管理。

超时后 Worker 收到 allowed: false，可选择替代方案或终止操作。

审批最佳实践

检查 tool_name：确认请求的操作类型
阅读 description：理解操作的具体内容和影响范围
审查 args：检查参数是否合理（特别是文件路径和命令内容）
谨慎批准 bash：命令执行是最敏感的操作

Tool 访问控制

Tool 分类

类别	Tool 名称	风险级别	生产环境
Safe	`read_file`、`write_file`、`edit_file`、`grep`、`glob`	低	允许
Risky	`bash`	高	需审批
Network	`web_fetch`	中	需审批
System	`agent`、`notebook_edit`、`todo_write`	低	按需

配置 allowed_tools

通过 init 的 config.allowed_tools 或 CLI --allowed-tools 限制 Session 可用工具：

{
  "config": {
    "allowed_tools": ["read_file", "write_file", "edit_file", "grep", "glob", "bash"],
    "disallowed_tools": ["web_fetch"]
  }
}

/perm 命令

使用 /perm 查看或修改当前 Session 的权限设置：

/perm              # 查看当前权限状态
/perm mode bypass  # 切换到 bypass 模式（慎用）
/perm mode default # 切换回默认模式

警告：bypass 模式下 AI Agent 可执行任何操作而不请求审批，仅在完全信任的场景下使用。

Bash 命令策略

CheckBashCommand() 检测 Bash 工具中的危险命令：

严重级	行为	示例
P0（自动拒绝）	直接阻止	`rm -rf /`、`dd of=/`、`mkfs`、fork bomb
P1（记录并标记）	记录日志并标记为高风险，实际确认由 Permission Request 系统处理	SSH key 访问、AWS 元数据探测、crontab 修改

安全审查 Bash 执行

当 AI 请求执行 Bash 命令时：

检查命令内容：permission_request 的 args 包含完整命令
识别管道和重定向：|、>、>> 可能改变命令行为
注意变量展开：$VAR、${VAR} 可能包含意外值
确认工作目录：相对路径依赖当前目录

环境变量安全

Gateway 注入的环境变量

Cron 执行和 Session 启动时，Gateway 注入以下环境变量：

变量	说明
`GATEWAY_BOT_ID`	当前 Bot 的平台运行时 ID（如 `U12345`）
`GATEWAY_BOT_NAME`	当前 Bot 的 YAML 配置名（如 `my-bot`），用于 agent config 路径解析
`GATEWAY_USER_ID`	当前用户的 ID
`GATEWAY_SESSION_ID`	当前 Session 的 ID

敏感变量保护

以下变量不会传递给 Worker 子进程：

AWS_*、ANTHROPIC_*、SLACK_* 等前缀匹配的凭证变量
API_KEY、DATABASE_URL 等精确匹配的敏感变量
CLAUDECODE（防止嵌套 Agent）
GATEWAY_TOKEN、GATEWAY_ADDR（Gateway 内部变量）

认证机制

API Key

internal/security/auth.go 提供三层 Key 提取（按优先级）：

HTTP Header（X-API-Key，可自定义）
Authorization Bearer（Authorization: Bearer <key>，缺省回退；适配 OpenAPI/Scalar 控制台与多数 SDK 默认行为）
Query Parameter（api_key，浏览器 WebSocket 客户端专用）

开发模式下未配置 API Key 时，所有请求以 anonymous 身份通过。生产环境必须配置 API Key。

API Key + Bot ID 认证

internal/security/auth.go 提供认证机制：

API Key：通过 X-API-Key Header、Authorization: Bearer <key> 或 ?api_key= Query Param 携带（三者等价，提取顺序见上文）。Authenticator 在内存 map 中验证，支持热重载（ReloadKeys）。
Bot ID：通过 X-Bot-ID Header 或 bot_id 查询参数指定 Bot 身份。每个 Bot 只能操作属于自己的 Session，禁止跨 Bot 访问。使用 security.BotIDFromRequest(r) 提取 Bot ID。

开发模式下未配置 API Key 时，所有请求以 anonymous 身份通过。生产环境必须配置 API Key。

APIKeyResolver（多用户映射）

通过 security.SetKeyResolver() 设置自定义的 APIKeyResolver，可将 API Key 映射到不同的 userID，实现用户级会话隔离：

security.SetKeyResolver(func(key string) (userID string, ok bool) {
    // 自定义映射逻辑：查数据库、查配置等
    return resolveKeyToUser(key)
})

未设置 resolver 时，所有 API Key 认证的请求统一使用 api_user 身份。

安全配置最佳实践

1. 最小权限原则

# 只允许必要的 Tool
allowed_tools: ["read_file", "grep", "glob"]

# 而不是全部开放
allowed_tools: ["*"]

2. 分环境配置

# config-dev.yaml
security:
  api_keys: []              # Dev 模式：无需认证
  tool_access: "all"        # 开放所有 Tool

# config-prod.yaml
security:
  api_keys: ["sk-xxx"]      # 强制认证
  tool_access: "safe_only"  # 仅 Safe 类 Tool

3. 定期轮换密钥

API Key 定期更新
使用编号式环境变量（HOTPLEX_SECURITY_API_KEY_1、_2）支持无损轮转

4. 审计日志

Gateway 的所有安全事件通过 slog JSON handler 记录：认证成功/失败、权限请求/响应、SSRF 拦截、Bash 策略触发、Session 状态转换。

5. 网络隔离

server:
  listen: "127.0.0.1:8888"  # 仅本地访问

生产部署时通过反向代理（Nginx/Caddy）暴露，Gateway 本身不直接对外监听。

SSRF 防护

internal/security/ssrf.go 实现四层 SSRF 检查：

层级	检查内容
1. 协议限制	仅允许 `http` 和 `https`
2. 裸 IP 检查	IP 字面值直接匹配 BlockedCIDRs
3. DNS 解析	解析主机名获取所有 IP
4. CIDR 匹配	所有解析 IP 检查是否在阻断列表

高敏感场景使用 ValidateURLDoubleResolve 防御 DNS rebinding 攻击。

命令白名单

仅允许执行两个二进制：claude 和 opencode。

命令名不得包含路径分隔符或危险字符
禁止 Shell 执行（不经过 /bin/sh）
通过 RegisterCommand() 可动态添加新命令