diff --git a/docs/faq.md b/docs/faq.md
index fa7e76475..4823c7011 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -11,6 +11,7 @@
 - [Installation fails: "manifest unknown" for embedded image](#installation-fails-manifest-unknown-for-embedded-image)
 - [Manager Agent startup timeout or failure](#manager-agent-startup-timeout-or-failure)
 - [Accessing the web UI from other devices on the LAN](#accessing-the-web-ui-from-other-devices-on-the-lan)
+- [Element says the homeserver URL is not a valid Matrix server](#element-says-the-homeserver-url-is-not-a-valid-matrix-server)
 - [Cannot connect to Matrix server locally](#cannot-connect-to-matrix-server-locally)
 - [How to talk to a Worker directly](#how-to-talk-to-a-worker-directly)
 - [How to connect third-party, local, or multi-provider models](#how-to-connect-third-party-local-or-multi-provider-models)
@@ -392,6 +393,20 @@ HiClaw host can reach each other in the Tailscale network.
 
 ---
 
+## Element says the homeserver URL is not a valid Matrix server
+
+When Element asks for a custom homeserver, do not enter the Element Web UI URL
+or port. These two URLs serve different components:
+
+- Element Web UI: `http://<host>:18088`
+- Matrix/Higress gateway homeserver: `http://<host>:18080`
+
+If you see "homeserver URL is not a valid Matrix server", replace `:18088` with
+`:18080`, then retry login. For LAN or Tailscale access, use the reachable host
+IP in the same format, for example `http://192.168.1.100:18080`.
+
+---
+
 ## Cannot connect to Matrix server locally
 
 If the Matrix server is unreachable even on the local machine, check whether a proxy is enabled in your browser or system. The `*-local.hiclaw.io` domain resolves to `127.0.0.1` by default — if traffic is routed through a proxy, requests will never reach the local server.
diff --git a/docs/zh-cn/faq.md b/docs/zh-cn/faq.md
index fa30c8684..9ef8bb655 100644
--- a/docs/zh-cn/faq.md
+++ b/docs/zh-cn/faq.md
@@ -11,6 +11,7 @@
 - [安装失败：embedded 镜像 "manifest unknown"](#安装失败embedded-镜像-manifest-unknown)
 - [Manager Agent 启动超时或失败](#manager-agent-启动超时或失败)
 - [局域网其他电脑如何访问 Web 端](#局域网其他电脑如何访问-web-端)
+- [Element 提示 homeserver 不是有效的 Matrix 服务器](#element-提示-homeserver-不是有效的-matrix-服务器)
 - [本地访问 Matrix 服务器不通](#本地访问-matrix-服务器不通)
 - [如何主动指挥 Worker](#如何主动指挥-worker)
 - [如何接入第三方、本地或多供应商模型](#如何接入第三方本地或多供应商模型)
@@ -381,6 +382,17 @@ http://<局域网IP>:18080
 
 ---
 
+## Element 提示 homeserver 不是有效的 Matrix 服务器
+
+Element 要求填写自定义 homeserver 时，不要填写 Element Web UI 的地址或端口。这两个地址对应不同组件：
+
+- Element Web UI：`http://<host>:18088`
+- Matrix/Higress gateway homeserver：`http://<host>:18080`
+
+如果看到“homeserver 不是有效的 Matrix 服务器”一类提示，请将 `:18088` 改成 `:18080` 后重新登录。局域网或 Tailscale 访问时，使用客户端能访问到的主机 IP，例如 `http://192.168.1.100:18080`。
+
+---
+
 ## 本地访问 Matrix 服务器不通
 
 如果在本机也无法连接 Matrix 服务器，请检查浏览器或系统是否开启了代理。`*-local.hiclaw.io` 域名默认解析到 `127.0.0.1`，开启代理后请求会被转发到代理服务器，无法到达本地服务。