Skip to content

docs: clarify Element homeserver port #978

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
RerankerGuo wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify Element homeserver port #978

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions docs/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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.
Expand Down
12 changes: 12 additions & 0 deletions docs/zh-cn/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
- [如何接入第三方、本地或多供应商模型](#如何接入第三方本地或多供应商模型)
Expand Down Expand Up @@ -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`，开启代理后请求会被转发到代理服务器，无法到达本地服务。
Expand Down