AegisGate Agent Skill

What is this document? This is an agent-executable skill document for AegisGate — an open-source LLM security gateway. It walks through installation, startup, token registration, upstream configuration, and client integration on a fresh machine.

本技能文档给 Agent 直接使用，目标是：在一台新机器上完成 AegisGate 的安装、启动、注册 token 或配置直连上游、以及客户端接入配置。

0) What does AegisGate do? 先读项目要点（必须）

• AegisGate 是 LLM 安全网关：请求侧脱敏/清洗，响应侧检测/自动净化（auto-sanitize）；responses 结构化 input（含 function/tool 输出）也会在转发上游前做脱敏。
• 两种路由模式（可同时启用）：
  • Token 路由（推荐多租户场景）：每个 token 绑定独立的上游地址；注册/管理 token 时需提供网关密钥。
    • v1（LLM）：http://<host>:18080/v1/__gw__/t/<TOKEN>/...
    • v2（通用 HTTP 代理）：http://<host>:18080/v2/__gw__/t/<TOKEN>，须携带 x-target-url: <完整目标URL> 请求头；且目标主机须在 AEGIS_V2_TARGET_ALLOWLIST 白名单内（默认空＝拒绝全部目标，fail-closed）
  • 直连上游（单用户/Agent 快速接入）：设置 AEGIS_UPSTREAM_BASE_URL=<上游地址> 后，可直接请求 /v1/...，无需注册 token。v2 仍必须使用 token 路径。
• 脱敏豁免字段（whitelist_key）：注册 token 时可指定逗号分隔的字段名列表（如 api_key,secret,token）。请求体中这些字段的值不做 PII 脱敏，直接透传到上游。适用于需要原始凭证通过的场景。支持以下匹配模式：
  • JSON："field":"value" 或 "field": "value"
  • 等号赋值：field=value
  • 冒号赋值：field:value
  • URL 查询参数：?field=value
  • 字段名约束：会被统一转为小写，且必须匹配 ^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$（首字符为字母/数字/下划线，总长 ≤64）。不匹配的键会被静默丢弃，注册接口不会报错——以 /__gw__/register 返回体中的 whitelist_key 为准，那是规范化后的实际生效值。
• 管理接口（/__gw__/register|lookup|unregister|add|remove）应只允许内网/管理机访问。

1) What are the prerequisites? 环境检查

uname -a
cat /etc/os-release
which docker || true
which docker-compose || true
git --version || true
python3 --version || true

2) How to install Docker? 如果没有 Docker：先安装（Ubuntu/Debian）

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
docker --version
docker compose version

可选（免 sudo）：

sudo usermod -aG docker "$USER"
newgrp docker

3) How to get the source code? 获取源码

3.1 Git 方式

git clone https://github.com/ax128/AegisGate.git
cd AegisGate

3.2 已有源码目录

cd /path/to/AegisGate

4) How to start AegisGate with Docker? 推荐安装方式

docker network create cliproxyapi_default || true
docker network create sub2api-deploy_sub2api-network || true
docker compose up -d --build
docker compose ps
docker compose logs -f aegisgate

说明：仓库自带 docker-compose.yml 默认引用上述 external networks；如果你的环境不需要这些上游网络，需先覆盖或移除对应 network 挂载，再启动。

健康检查：

curl -sS http://127.0.0.1:18080/health

就绪检查（readiness，可选）：

curl -sS http://127.0.0.1:18080/ready

5) How to run without Docker? 源码本地运行

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .
uvicorn aegisgate.core.gateway:app --host 127.0.0.1 --port 18080 --no-proxy-headers

可选依赖组：.[redis] / .[postgres] / .[observability]；要跑测试用 .[dev]（CI 用的是 pip install -e ".[dev,semantic]"）。语义复核本身不需要任何 extra——它只调 AEGIS_SEMANTIC_SERVICE_URL 指向的外部服务。

6) How to connect upstream LLM providers? 接入方式选择

6.1 What is token routing? Token 路由（多租户，推荐）

注册上游并生成 token：

# gateway_key 从 cat config/aegis_gateway.key 获取
curl -X POST http://127.0.0.1:18080/__gw__/register \
  -H "Content-Type: application/json" \
  -d '{"upstream_base":"https://your-upstream.example.com/v1","gateway_key":"<AEGIS_GATEWAY_KEY>"}'

期望返回：

{
  "token": "ExampleToken24CharsAbc12",
  "baseUrl": "http://127.0.0.1:18080/v1/__gw__/t/ExampleToken24CharsAbc12",
  "whitelist_key": []
}

注册时可附带脱敏豁免字段（如 api_key 字段值不做脱敏）：

curl -X POST http://127.0.0.1:18080/__gw__/register \
  -H "Content-Type: application/json" \
  -d '{"upstream_base":"https://your-upstream.example.com/v1","gateway_key":"<AEGIS_GATEWAY_KEY>","whitelist_key":["api_key","secret"]}'

6.2 What is direct upstream mode? 直连上游（单用户/Agent 快速接入）

在 config/.env 中设置：

AEGIS_UPSTREAM_BASE_URL=https://your-upstream.example.com/v1

重启后直接请求 /v1/...，无需注册 token。/v2/... 不支持直连模式，仍需使用 /v2/__gw__/t/<TOKEN>/...：

curl -X POST http://127.0.0.1:18080/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <UPSTREAM_API_KEY>" \
  -d '{"model":"gpt-5.4-mini","input":"hello"}'

7) How to verify the gateway is working? 验证调用

Token 路由

curl -X POST "http://127.0.0.1:18080/v1/__gw__/t/<TOKEN>/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <UPSTREAM_API_KEY>" \
  -d '{"model":"gpt-5.4-mini","input":"hello"}'

直连上游

curl -X POST "http://127.0.0.1:18080/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <UPSTREAM_API_KEY>" \
  -d '{"model":"gpt-5.4-mini","input":"hello"}'

8) How to configure AI agents and clients? 客户端配置模板

Token 路由

provider: openai_compatible
base_url: http://127.0.0.1:18080/v1/__gw__/t/<TOKEN>
api_key: <UPSTREAM_API_KEY>
model: gpt-5.4-mini

直连上游

provider: openai_compatible
base_url: http://127.0.0.1:18080/v1
api_key: <UPSTREAM_API_KEY>
model: gpt-5.4-mini

说明：

• 若客户端默认流式输出，/v1/chat/completions 与 /v1/responses 在上游提前断流时会补终止信号； /v1/messages 与通用 /v1/<子路径> 没有这个分支，见 README.md 的 Troubleshooting。
• 直连模式下不需要 base_url 携带 token 路径段。

9) How to manage tokens and the gateway? 常用管理命令

查看 token（按 upstream_base 查询已注册项）：

curl -X POST http://127.0.0.1:18080/__gw__/lookup \
  -H "Content-Type: application/json" \
  -d '{"upstream_base":"https://your-upstream.example.com/v1","gateway_key":"<AEGIS_GATEWAY_KEY>"}'

删除 token：

curl -X POST http://127.0.0.1:18080/__gw__/unregister \
  -H "Content-Type: application/json" \
  -d '{"token":"<TOKEN>","gateway_key":"<AEGIS_GATEWAY_KEY>"}'

查看所有 token（最稳妥：直接读本机映射文件）：

cat config/gw_tokens.json

通过 UI API 查看所有 token（GET /__ui__/api/tokens 不是 X-Gateway-Key 直调接口；需要 session cookie）：

# 1) 登录 UI，获取 session cookie
curl -c /tmp/aegisgate-ui.cookie -X POST http://127.0.0.1:18080/__ui__/api/login \
  -H "Content-Type: application/json" \
  -d '{"password":"<AEGIS_GATEWAY_KEY>"}'

# 2) 使用已登录 session 查看 token 列表
curl -b /tmp/aegisgate-ui.cookie http://127.0.0.1:18080/__ui__/api/tokens

说明：

• 若 curl 调用 UI API 返回 401，通常是因为 AEGIS_LOCAL_UI_SECURE_COOKIE=true（默认）会下发 Secure cookie，http://127.0.0.1 场景下 cookie 不会被回传；此时请改用 HTTPS 访问 UI，或临时设置 AEGIS_LOCAL_UI_SECURE_COOKIE=false 后重启网关再测试（仅建议开发环境）。
• UI 写接口除 session 外还要求 x-aegis-ui-csrf；可通过 GET /__ui__/api/bootstrap 读取当前 session 的 csrf token。

查看日志：

docker compose logs -f aegisgate

重启：

docker compose restart aegisgate

升级：

git pull
docker compose up -d --build

10) How to troubleshoot issues? 故障排查顺序

1. health 是否正常（curl http://127.0.0.1:18080/health）。
2. 确认使用哪种路由模式：token 路由（路径含 /v1/__gw__/t/<TOKEN>/...）或直连上游（AEGIS_UPSTREAM_BASE_URL 是否已设置）。
3. Token 路由：若只知道 upstream_base，用 POST /__gw__/lookup 反查 token；若只知道 token，可查看 config/gw_tokens.json 或登录 UI 后访问 /__ui__/api/tokens。同时确认上游地址与 API key 是否正确。
4. 直连模式：.env 中 AEGIS_UPSTREAM_BASE_URL 是否正确，是否已重启。
5. 看 docker compose logs -f aegisgate 是否有 upstream 错误、自动净化（auto-sanitize）、阻断原因。

11) What are the security best practices? 安全基线

• 对外仅暴露业务入口，管理接口仅限内网。
• 默认监听建议使用 127.0.0.1，通过反向代理做外部暴露控制。
• 不在日志或工单中明文粘贴密钥、token、cookie、私钥、助记词。
• 生产环境定期轮换 config/aegis_gateway.key（替换文件内容后重启服务）。
• whitelist_key 字段只填真正需要豁免脱敏的字段名，最小化敏感数据明文透传范围。

12) Where to read more? 相关文档

• README.md / README_zh.md：完整能力、环境变量与安全边界
• UPSTREAM-QUICKSTART.md：CLIProxyAPI / Sub2API / AIClient-2-API 接入
• WEBUI-QUICKSTART.md：Web 控制台与 __ui__ 接口契约
• OTHER_TERMINAL_CLIENTS_USAGE.md：终端与 IDE 客户端
• config/README.md：挂载配置目录与热更新限制