diff --git a/yunke-server/app/api/routers/customer.py b/yunke-server/app/api/routers/customer.py
index a3187fe..142d40f 100644
--- a/yunke-server/app/api/routers/customer.py
+++ b/yunke-server/app/api/routers/customer.py
@@ -2,10 +2,11 @@
 
 Read-only query over the mirrored ``customer`` table. Supports filtering by
 ``channel``, ``owner_account_id``, ``user_id``, ``add_time_since`` and
-``last_chat_since`` (direct columns) and ``department_id`` (resolved through
-``customer.user_id`` -> ``staff.dept_id``). Results are ordered by
-``last_chat_time desc`` (nulls last) then ``friend_id`` so the
-most-recently-active contacts surface first.
+``last_chat_since`` (direct columns), ``department_id`` (resolved through
+``customer.user_id`` -> ``staff.dept_id``) and ``q`` (substring match on
+nickname / remark / friend_id / phone, ``%``/``_`` escaped as literals — the
+通讯录 search box). Results are ordered by ``last_chat_time desc`` (nulls
+last) then ``friend_id`` so the most-recently-active contacts surface first.
 """
 
 from __future__ import annotations
@@ -72,6 +73,7 @@ async def list_customers(
     user_id: Annotated[str | None, Query()] = None,
     add_time_since: Annotated[int | None, Query(ge=0)] = None,
     last_chat_since: Annotated[int | None, Query(ge=0)] = None,
+    q: Annotated[str | None, Query()] = None,
 ) -> Page[CustomerOut]:
     """List customers with optional filters and pagination."""
     conditions = []
@@ -79,6 +81,19 @@ async def list_customers(
         conditions.append(Customer.channel == channel)
     if owner_account_id is not None:
         conditions.append(Customer.owner_account_id == owner_account_id)
+    if q:
+        # LIKE 通配符转义: %/_ 按字面匹配(镜像 messages.py 的 q 处理)。
+        # 对齐云客通讯录搜索:昵称/微信号/备注名/手机号四列任一含词即命中。
+        escaped = q.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+        like = f"%{escaped}%"
+        conditions.append(
+            sa.or_(
+                Customer.friend_nickname.like(like, escape="\\"),
+                Customer.friend_remark.like(like, escape="\\"),
+                Customer.friend_id.like(like, escape="\\"),
+                Customer.phone.like(like, escape="\\"),
+            )
+        )
     if department_id is not None:
         # Customer has no dept column; resolve via the owning staff member.
         dept_user_ids = sa.select(Staff.user_id).where(
diff --git a/yunke-server/app/api/routers/groups.py b/yunke-server/app/api/routers/groups.py
index 9bafa3c..2ac8767 100644
--- a/yunke-server/app/api/routers/groups.py
+++ b/yunke-server/app/api/routers/groups.py
@@ -2,8 +2,9 @@
 
 * ``GET /api/groups`` -> ``Page[GroupOut]`` filtered by ``channel`` /
   ``owner_account_id`` / ``user_id`` (the latter mapping to the
-  ``owner_user_id`` column), ordered by ``last_chat_time desc`` (nulls last)
-  so recently-active groups surface first.
+  ``owner_user_id`` column) and ``q`` (substring match on ``room_name``,
+  ``%``/``_`` escaped as literals — the 通讯录群 tab search box), ordered by
+  ``last_chat_time desc`` (nulls last) so recently-active groups surface first.
 * ``GET /api/groups/{room_id}/members`` -> ``list[GroupMemberOut]`` — the
   members of a single group (small set, no pagination needed).
 """
@@ -36,20 +37,26 @@ async def list_groups(
     owner_account_id: Annotated[str | None, Query()] = None,
     user_id: Annotated[str | None, Query()] = None,
     room_id: Annotated[str | None, Query()] = None,
+    q: Annotated[str | None, Query()] = None,
 ) -> Page[GroupOut]:
     """List chat groups with optional ``channel`` / ``owner_account_id`` /
-    ``user_id`` / ``room_id`` filters.
+    ``user_id`` / ``room_id`` / ``q`` filters.
 
     ``user_id`` maps to the ``ChatGroup.owner_user_id`` column (the staff
     ``userId`` who owns the chatroom account), mirroring the ``user_id``
     filter on ``GET /api/customers``. ``room_id`` is an exact-match single-
-    row lookup (chat page group-name resolution).
+    row lookup (chat page group-name resolution). ``q`` is a substring match
+    on ``room_name``.
     """
     conditions = []
     if channel is not None:
         conditions.append(ChatGroup.channel == channel)
     if owner_account_id is not None:
         conditions.append(ChatGroup.owner_account_id == owner_account_id)
+    if q:
+        # LIKE 通配符转义: %/_ 按字面匹配(镜像 customers/messages 的 q 处理)
+        escaped = q.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+        conditions.append(ChatGroup.room_name.like(f"%{escaped}%", escape="\\"))
     if room_id is not None:
         conditions.append(ChatGroup.room_id == room_id)
     if user_id is not None:
diff --git a/yunke-server/tests/test_api_customers.py b/yunke-server/tests/test_api_customers.py
index d50ad07..a47feea 100644
--- a/yunke-server/tests/test_api_customers.py
+++ b/yunke-server/tests/test_api_customers.py
@@ -73,3 +73,78 @@ async def test_customers_today_send_receive(make_client):
     assert by_fid["f1"]["receive_today"] == 2
     assert by_fid["f2"]["send_today"] == 0
     assert by_fid["f2"]["receive_today"] == 0
+
+
+# ---------------------------------------------------------------------------
+# GET /api/customers?q= — 文本搜索(昵称/备注/friend_id/手机号,LIKE 通配转义)
+# 对齐云客通讯录搜索框「支持微信昵称、微信号、备注名、手机号搜索」。
+# ---------------------------------------------------------------------------
+
+async def _seed_q(session):
+    from app.db.models import Customer as C
+
+    session.add_all([
+        # 昵称命中「阿里」
+        C(channel="wechat", owner_account_id="o1", friend_id="wx_nick",
+          friend_nickname="阿里巴巴顾问"),
+        # 备注命中「阿里」
+        C(channel="wechat", owner_account_id="o1", friend_id="wx_remark",
+          friend_nickname="腾讯小哥", friend_remark="阿里系客户"),
+        # 不含词;手机号唯一可命中
+        C(channel="wechat", owner_account_id="o1", friend_id="wx_plain",
+          friend_nickname="网易产品", friend_remark="同行", phone="13900002222"),
+        # friend_id 唯一可命中;顺带另一手机号
+        C(channel="wechat", owner_account_id="o1", friend_id="wxid_ali888",
+          friend_nickname="字节跳动", phone="13866668888"),
+    ])
+    await session.commit()
+
+
+async def test_q_matches_nickname_and_remark(make_client):
+    """q=阿里 -> 昵称命中 + 备注命中(2 行),其余行不回。"""
+    client = await make_client(_seed_q)
+    r = await client.get("/api/customers", params={"q": "阿里"})
+    assert r.status_code == 200
+    body = r.json()
+    assert body["total"] == 2
+    assert {it["friend_id"] for it in body["items"]} == {"wx_nick", "wx_remark"}
+
+
+async def test_q_matches_friend_id_and_phone(make_client):
+    """q 命中 friend_id / phone 两列。"""
+    client = await make_client(_seed_q)
+    r = await client.get("/api/customers", params={"q": "ali888"})
+    assert r.status_code == 200
+    assert {it["friend_id"] for it in r.json()["items"]} == {"wxid_ali888"}
+    r2 = await client.get("/api/customers", params={"q": "1390000"})
+    assert r2.status_code == 200
+    assert {it["friend_id"] for it in r2.json()["items"]} == {"wx_plain"}
+
+
+async def test_q_empty_no_filter(make_client):
+    """q 空串 -> 不过滤,全量返回。"""
+    client = await make_client(_seed_q)
+    r = await client.get("/api/customers", params={"q": ""})
+    assert r.status_code == 200
+    assert r.json()["total"] == 4
+
+
+async def test_q_escapes_like_wildcards(make_client):
+    """q 里的 % 按字面匹配(镜像 messages 的 q 转义行为)。"""
+
+    async def seed(session):
+        from app.db.models import Customer as C
+
+        session.add_all([
+            C(channel="wechat", friend_id="wx_pct", friend_nickname="折扣100%off"),
+            C(channel="wechat", friend_id="wx_digit", friend_nickname="折扣1001off"),
+        ])
+        await session.commit()
+
+    client = await make_client(seed)
+    r = await client.get("/api/customers", params={"q": "100%"})
+    assert r.status_code == 200
+    body = r.json()
+    # 只命中字面含 "100%" 的行;不因 % 通配漏扩到 "1001"
+    assert body["total"] == 1
+    assert [it["friend_id"] for it in body["items"]] == ["wx_pct"]
diff --git a/yunke-server/tests/test_api_groups.py b/yunke-server/tests/test_api_groups.py
index e26e73b..6dfb4cb 100644
--- a/yunke-server/tests/test_api_groups.py
+++ b/yunke-server/tests/test_api_groups.py
@@ -303,3 +303,25 @@ async def test_groups_owner_fields_default_null(make_client):
     for key in ("owner_name", "owner_wxid", "owner_alias",
                 "owner_avatar", "friend_count", "create_time"):
         assert item[key] is None
+
+
+# ---------------------------------------------------------------------------
+# GET /api/groups?q= — 群名称模糊搜索(通讯录群 tab 搜索框,LIKE 通配转义)
+# ---------------------------------------------------------------------------
+
+async def test_q_room_name_substring_filter(make_client):
+    """``?q=Team A`` -> 群名子串匹配(LIKE 默认大小写敏感);q 空串不过滤。"""
+    client = await make_client(_seed)
+    r = await client.get("/api/groups", params={"q": "Team A"})
+    assert r.status_code == 200
+    body = r.json()
+    assert body["total"] == 1
+    assert body["items"][0]["room_id"] == "room_a@chatroom"
+    # 子串跨行命中: "Team" 同时出现在 Team A / Team B / WA Team
+    r2 = await client.get("/api/groups", params={"q": "Team"})
+    assert {it["room_id"] for it in r2.json()["items"]} == {
+        "room_a@chatroom", "room_b@chatroom", "wa_room_x@s.whatsapp.net",
+    }
+    # 空串 -> 不过滤
+    r3 = await client.get("/api/groups", params={"q": ""})
+    assert r3.json()["total"] == 3