diff --git a/README.md b/README.md
index 58975408d..e047166d6 100644
--- a/README.md
+++ b/README.md
@@ -58,6 +58,10 @@ docker run --rm -it \
 > `https://github.com/Hmbown/CodeWhale/releases`. For manual downloads,
 > verify the SHA-256 manifest and avoid look-alike repositories or search-result
 > mirrors. See [download safety and checksums](docs/INSTALL.md#2-download-safety-and-checksums).
+>
+> macOS Gatekeeper: standalone downloads from a browser may show "Apple cannot verify"
+> warnings. Clear the quarantine attribute on both binaries:
+> `xattr -d com.apple.quarantine ~/.local/bin/codewhale ~/.local/bin/codewhale-tui`.
 
 Already installed? Use the updater that matches the install path:
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 97fd11eb3..7dbe807a4 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -53,6 +53,10 @@ docker run --rm -it \
 > `https://github.com/Hmbown/CodeWhale/releases`。手动下载时请校验
 > SHA-256 manifest，并避免相似仓库名或搜索结果里的镜像站。详见
 > [下载安全与校验](docs/INSTALL.md#2-download-safety-and-checksums)。
+>
+> macOS Gatekeeper：用浏览器手动下载时，可能会提示“Apple 无法验证”。
+> 这时可清理二进制的隔离属性：
+> `xattr -d com.apple.quarantine ~/.local/bin/codewhale ~/.local/bin/codewhale-tui`。
 
 已经安装过？按你的安装方式更新：
 
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 2a9fd17b4..ab4ef018d 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -266,6 +266,13 @@ chmod +x ~/.local/bin/codewhale ~/.local/bin/codewhale-tui
 codewhale --version
 ```
 
+> **macOS Gatekeeper note.** If you downloaded the binaries with a browser,
+> macOS may block them with "Apple cannot verify" warnings. Clear the quarantine
+> attribute on both binaries and retry:
+> ```bash
+> xattr -d com.apple.quarantine ~/.local/bin/codewhale ~/.local/bin/codewhale-tui 2>/dev/null || true
+> ```
+
 Verify integrity against the per-release SHA-256 manifest:
 
 ```bash