4月 19, 2026

OpenClaw Node App 聯絡人（Contacts）指令完全攻略｜搜尋、新增、通訊錄管理

OpenClaw Node App 聯絡人（Contacts）指令完全攻略

這篇文章會介紹 OpenClaw Node App 的「聯絡人」功能，讓你能夠搜尋和新增手機上的聯絡人資料。

實驗日期：2026-04-19

實驗設備：Vivo V2514（Android 16）

OpenClaw 版本：2026.4.19.10ver（ThirdParty）

一、什麼是 Contacts 功能？

想像一下

當你安裝 OpenClaw Node App 並連線到你的手機後，你可以：

🔍 搜尋聯絡人：快速找到通訊錄中的朋友、同事
➕ 新增聯絡人：直接透過指令新增聯絡人到手機
📋 讀取完整資料：取得聯絡人的電話、郵件、公司等資訊

實用場景

🔍 快速查詢：想知道某人的電話號碼
📱 自動化新增：當收到陌生來電時，自動新增為聯絡人
📤 匯入聯絡人：透過腳本批量新增聯絡人
🔄 同步整理：整理手機上的通訊錄

二、Contacts 指令家族

根據官方文件和原始碼分析，Contacts 有 2 個指令：

指令	功能
`contacts.search`	搜尋聯絡人
`contacts.add`	新增聯絡人

三、指令詳細說明

1. contacts.search - 搜尋聯絡人

用途： 在手機通訊錄中搜尋聯絡人

指令格式：

openclaw nodes invoke --node "V2514" --command contacts.search --params '{
  "query": "關鍵字",
  "limit": 25
}'

參數說明：

參數	類型	預設值	說明
`query`	string	null	搜尋關鍵字（姓名）
`limit`	int	25	回傳數量（最大 200）

2. contacts.add - 新增聯絡人

用途： 將新聯絡人新增到手機通訊錄

指令格式：

openclaw nodes invoke --node "V2514" --command contacts.add --params '{
  "givenName": "名",
  "familyName": "姓",
  "displayName": "顯示名稱",
  "organizationName": "公司",
  "phoneNumbers": ["電話號碼"],
  "emails": ["電子郵件"]
}'

參數說明：

參數	類型	必填	說明
`givenName`	string	至少一個	名
`familyName`	string	至少一個	姓
`displayName`	string	至少一個	顯示名稱
`organizationName`	string	❌	公司/組織
`phoneNumbers`	array	至少一個	電話號碼陣列
`emails`	array	❌	電子郵件陣列

注意： 必須至少提供「姓名」、「公司」或「電話/郵件」其中之一。

四、回傳資料格式

contacts.search 回傳

{
  "contacts": [
    {
      "identifier": "747",
      "displayName": "AI小風同學",
      "givenName": "小風同學",
      "familyName": "AI",
      "organizationName": "",
      "phoneNumbers": [],
      "emails": []
    }
  ]
}

欄位說明：

欄位	類型	說明
`identifier`	string	聯絡人唯一 ID
`displayName`	string	顯示名稱
`givenName`	string	名
`familyName`	string	姓
`organizationName`	string	公司/組織
`phoneNumbers`	array	電話號碼列表
`emails`	array	電子郵件列表

contacts.add 回傳

{
  "contact": {
    "identifier": "804",
    "displayName": "使用者測試",
    "givenName": "測試",
    "familyName": "使用者",
    "organizationName": "",
    "phoneNumbers": ["0912345678"],
    "emails": ["test@example.com"]
  }
}

五、實際測試結果

測試 1：基本搜尋

openclaw nodes invoke --node "V2514" --command contacts.search --params '{}'

結果： ✅ 成功！回傳了所有聯絡人

{
  "contacts": [
    { "identifier": "758", "displayName": "(unnamed)", ... },
    { "identifier": "747", "displayName": "AI小風同學", ... },
    ...
  ]
}

測試 2：關鍵字搜尋

openclaw nodes invoke --node "V2514" --command contacts.search --params '{
  "query": "小風",
  "limit": 3
}'

結果： ✅ 成功！找到 2 筆記錄

{
  "contacts": [
    { "displayName": "AI小風同學", "givenName": "小風同學", "familyName": "AI" },
    { "displayName": "小風同學", "givenName": "", "familyName": "小風同學" }
  ]
}

測試 3：新增聯絡人

openclaw nodes invoke --node "V2514" --command contacts.add --params '{
  "givenName": "測試",
  "familyName": "使用者",
  "phoneNumbers": ["0912345678"],
  "emails": ["test@example.com"]
}'

結果： ✅ 成功！新增了「使用者測試」聯絡人

{
  "contact": {
    "identifier": "804",
    "displayName": "使用者測試",
    "givenName": "測試",
    "familyName": "使用者",
    "phoneNumbers": ["0912345678"],
    "emails": ["test@example.com"]
  }
}

測試 4：空資料錯誤處理

openclaw nodes invoke --node "V2514" --command contacts.add --params '{}'

結果： ✅ 正確的錯誤處理

CONTACTS_INVALID: include a name, organization, phone, or email

六、使用範例

範例 1：查詢某人的電話

# 搜尋聯絡人
openclaw nodes invoke --node "V2514" --command contacts.search --params '{
  "query": "林富美"
}'

範例 2：快速新增聯絡人

openclaw nodes invoke --node "V2514" --command contacts.add --params '{
  "givenName": "小明",
  "familyName": "王",
  "phoneNumbers": ["0911222333"]
}'

範例 3：新增有公司資訊的聯絡人

openclaw nodes invoke --node "V2514" --command contacts.add --params '{
  "givenName": "約翰",
  "familyName": "史密斯",
  "organizationName": "XYZ 公司",
  "phoneNumbers": ["0223456789"],
  "emails": ["john@xyz.com"]
}'

範例 4：自動化腳本 - 新增未知來電者

假設你收到一通陌生電話，想要直接新增為聯絡人：

# 假設電話號碼是 0987654321
openclaw nodes invoke --node "V2514" --command contacts.add --params '{
  "givenName": "未知",
  "phoneNumbers": ["0987654321"]
}'

七、注意事項

1. 需要聯絡人權限

Contacts 功能需要以下權限：

權限	用途	需要的指令
READ_CONTACTS	讀取聯絡人	`contacts.search`
WRITE_CONTACTS	寫入聯絡人	`contacts.add`

開啟方式：

在 Android 設定中授權「聯絡人」權限
路徑：設定 → 應用程式 → OpenClaw Node → 權限 → 聯絡人

2. contacts.add 是危險命令

contacts.add 屬於「危險命令」，預設不會啟用。你需要在 Gateway 設定中手動開啟：

openclaw config set gateway.nodes.allowCommands '["contacts.add", ...]'

3. 名稱顯示規則

當你只提供 givenName 或 familyName 時，系統會自動組合：

提供的參數	顯示名稱
僅 `givenName: "小明"`	"小明"
僅 `familyName: "王"`	"王"
`givenName: "小明"` + `familyName: "王"`	"王小明"

4. 電話號碼類型

目前 contacts.add 新增的電話號碼會被設為「手機」類型（TYPE_MOBILE）。如果你需要其他類型（如家用、公司），可能需要等待未來版本更新。

八、與其他功能的比較

Contacts vs CallLog

功能	用途	資料類型
Contacts	聯絡人管理	通訊錄
CallLog	通話記錄	歷史通話

Contacts vs SMS

功能	用途	資料類型
Contacts	聯絡人管理	通訊錄
SMS	簡訊	簡訊記錄

九、常見問題

Q1：為什麼有些聯絡人顯示「(unnamed)」？

A：這是因為該聯絡人沒有設定姓名，只有一個電話號碼或郵件。這在行銷電話或快遞通知中很常見。

Q2：可以刪除聯絡人嗎？

A：目前 OpenClaw Node App 的 Contacts 功能只支援搜尋和新增，不支援刪除。這是因為刪除聯絡人需要 WRITECALLLOG 以外的更多權限。

Q3：可以修改現有的聯絡人嗎？

A：目前不支援修改功能，只能新增。如果需要修改，可以先刪除再重新新增（但需要自己記錄 identifier）。

Q4：為什麼新增成功但查不到？

A：有些手機可能需要重新開啟通訊錄 App 或重啟手機才能看到新新增的聯絡人。這是 Android 系統的行為，與 OpenClaw 無關。

十、結語

Contacts 功能是 OpenClaw Node App 中管理通訊錄的功能。它讓你能夠：

🔍 搜尋聯絡人：快速找到手機上的任何聯絡人
➕ 新增聯絡人：直接透過指令新增新聯絡人
📋 讀取完整資訊：取得電話、郵件、公司等詳細資料

這個功能完全運行在你的本地裝置上，不會將聯絡人資料上傳到任何雲端伺服器，隱私安全有保障。

文章更新：2026-04-19

感謝微風提供測試設備和建議！

搜尋此網誌

點點滴滴