diff --git a/README.md b/README.md
index dc155dd..9073e3f 100644
--- a/README.md
+++ b/README.md
@@ -590,6 +590,28 @@ curl -s http://127.0.0.1:18080/api/schema | jq        # 人读：items + resourc
 | 图标上传 | `POST /api/icon`（multipart，字段 `file`） |
 | 重建导航分区 | `POST /api/reload` |
 
+### 接口注意事项（agent 最容易踩的四点）
+
+1. **前缀是 `/admin/api`**（经统一入口）；容器内也可直连 `http://127.0.0.1:3005/api`。
+   根路径 `/api/` 不是管理接口：打到那里会得到 **200 + Dashy 的 HTML**，看着像成功其实什么都没改。
+   判断是否命中看返回体类型（JSON vs `<!DOCTYPE html>`），别只看状态码。
+2. **路由表是整表替换**：必须提交完整 `{"routes":[…]}`。只给单个路由对象会被 400 拒绝并提示；
+   清空非空表要显式 `force:true`。该接口只改路由表，**不会**动入口端口/TLS/认证地址等其它字段。
+3. **改完必须 apply**：`POST /admin/api/gateway/apply` 先做 `nginx -t` 校验，不通过则保留上一份
+   可用配置，并把 nginx 报错原文返回给你（不会把入口改坏）。
+4. **apply 之后是异步 reload**，不是同步生效：立刻探测可能拿到旧结果（表现为"明明 apply 了却 404"）。
+   正确做法是轮询等入口就绪：
+
+   ```bash
+   HOST=app.example.com
+   for i in $(seq 1 20); do
+     code=$(curl -s -o /dev/null -w '%{http_code}' -m 3 --resolve "$HOST:3080:127.0.0.1" "https://$HOST:3080/")
+     [ "$code" != "000" ] && break
+     sleep 0.5
+   done
+   echo "$code"
+   ```
+
 **示例：让 agent 一次性把站点改成你要的样子**
 
 ```bash