Iva Telegram AI 助理自行託管部署教學

您要建置的內容

Iva 是一個自行託管的 Telegram AI 助理，也是少數不必開放任何入站連接埠、也不必指向網域即可部署的服務之一。由於伺服器上沒有任何服務監聽公開介面，因此也不需要憑證。服務會向 Telegram 建立出站連線並維持連線，從回覆中讀取您的訊息。其餘功能都建立在這個單一出站連線上。

Iva 採用 MIT 授權，並以 Node 撰寫。它的記憶資料是由純 markdown 檔案組成的資料夾，Obsidian 可直接開啟這些檔案，因此即使不使用應用程式，服務記錄的您的相關筆記仍可讀取。本指南固定使用於 2026 年 8 月 6 日發布的 v0.3.13 版本。儲存庫之後已從 smixs/iva 重新命名為 smixs/iva-agent，以下指令使用新名稱。

大多數自行託管的軟體都從 DNS（網域名稱系統）記錄和 使用 Certbot 核發的 Let's Encrypt 憑證開始。Iva 完全略過這一層，因此只允許 SSH 通行的防火牆後方小型 VPS，就足以完成部署。

Iva 為何不需要開放連接埠

iva-telegram-poll.service 是長輪詢橋接程式。它會呼叫 Telegram 的 getUpdates API 並等待回應，因此每個連線都由您的伺服器發起。Telegram 不會反向連入，因此不需要設定反向代理，也不必擔心忘記續期憑證。

代理程式本身確實會監聽，但只監聽 127.0.0.1 連接埠 8723。專案文件對此有明確說明：不要暴露連接埠 8723；若在它前方設定反向代理，必須保留 bearer token 要求。安裝完成後，請檢查繫結位址。

sudo ss -tlnp | grep 8723

位址必須顯示為 127.0.0.1:8723。像 0.0.0.0:8723 這類萬用位址表示代理程式的 HTTP 路由可從網際網路存取。您應在讓機器人處理任何私人資訊前修正此設定。

因此防火牆維持關閉狀態。啟用防火牆前，請先允許 SSH，因為在沒有 SSH 規則的情況下執行 ufw enable 會關閉您目前輸入指令的工作階段。

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

單行安裝程式實際執行的內容

專案首頁提供一個指令，會將 GitHub 上的 script 透過管線傳給 bash。請先閱讀該 script，因為它執行的工作遠不只安裝一個程式。

curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/install.sh -o iva-install.sh
less iva-install.sh

• 使用偵測到的 package manager 安裝系統套件：git、gh、python3、ffmpeg、pandoc 和 poppler-utils。
• 當主機的 RAM 少於 1.5 GB 且沒有 swap 時，在 /swapfile 建立 2 GB 的 swapfile，因為沒有 swap 時，建置程序會被終止。
• 安裝 nvm，接著安裝 Node 24。這是 Iva 執行所需的最低版本。
• 將 Python package manager uv 安裝到 ~/.local/bin。
• 將 repository 複製到 ~/iva，並執行 npm ci。
• 將 agent-browser 安裝為全域 npm package。該套件接著會下載 Chromium，並在不使用 sudo 的情況下，將 Google Workspace CLI gws 放置到 ~/.local。
• 執行設定精靈、建置專案，並建立 vault。
• 將 iva 指令寫入 ~/.local/bin，並安裝 systemd user units。

單一指令會安裝這麼多軟體。這也說明 README 為何要求使用一般使用者身分安裝，而不是以 root 身分安裝：agent 的 shell tool 之後會以安裝程式當時具備的權限執行。該 script 只有在安裝套件與 swapfile 時使用 sudo，以及可能在 Chromium 步驟再使用一次；它透過一個 helper，在你已經是 root 時直接執行指令。

安裝前建立專用使用者

為 Iva 建立專用帳號。此代理程式會透過 Node 的 child_process 在主機上執行 shell 命令，沒有容器或沙箱，因此執行該代理程式的帳號就是安全邊界。

sudo adduser --disabled-password --gecos "" iva
sudo usermod -aG sudo iva
sudo install -d -m 700 -o iva -g iva /home/iva/.ssh
sudo cp ~/.ssh/authorized_keys /home/iva/.ssh/authorized_keys
sudo chown iva:iva /home/iva/.ssh/authorized_keys
sudo chmod 600 /home/iva/.ssh/authorized_keys
sudo loginctl enable-linger iva

enable-linger 很重要，因為 Iva 會以 systemd user unit 執行。未啟用 linger 時，systemd 會在該使用者的最後一個工作階段結束後立即停止其服務，因此關閉 SSH 後，助理也會停止。同一項規則也適用於您在 systemd 下自行建立的 服務和計時器。

只有在安裝程式新增套件期間，該帳號才需要 sudo。安裝完成後請移除這項權限。

sudo deluser iva sudo

直接以該使用者透過 SSH 登入。使用 sudo -iu iva 進入的 shell 不會設定 DBUS_SESSION_BUS_ADDRESS 或 XDG_RUNTIME_DIR，因此每個 systemctl --user 命令都會因 Failed to connect to bus 而失敗。建立這項界線，與 使用最低權限使用者執行服務 的做法相同。

安裝固定版本，而不是將腳本直接導向 bash

安裝程式有一項實用特性。在複製任何內容前，它會檢查腳本所在的目錄是否已經包含一個內有 "eve" 的 package.json。如果有，安裝程式會建置該份 checkout，並略過複製步驟。因此，您可以自行選擇版本。

git clone --branch v0.3.13 https://github.com/smixs/iva-agent.git ~/iva
cd ~/iva
git log -1 --oneline
bash install.sh

現在您知道實際執行的是哪份程式碼。如果腳本在當下直接複製處於任意狀態的 main，您就無法確認這一點。Iva 在 2026 年 8 月 4 日至 6 日間發布了 5 個版本，因此今天早上的 main 和今天下午的 main 並不是同一個程式。

checkout 標籤後，git 會處於 detached HEAD 狀態。這樣仍可正常執行，但請了解其限制：iva update 會將 checkout 推進到更新分支，因此固定版本只是已知的起點，不是永久凍結。iva version 會顯示套件版本與 git commit，讓您隨時確認目前使用的版本。

若要有意移至較新的版本，請先列出標籤，將您選取的標籤代入下方的 v0.3.13 並執行 checkout，然後再次從該 checkout 目錄內執行安裝程式。安裝程式本身沒有設定發布標籤的選項。其文件列出的環境變數為 REPO_URL、BRANCH 和 INSTALL_DIR，因此只有透過 git checkout 才能固定版本。

cd ~/iva
git fetch --tags
git tag --list 'v*' | sort -V | tail -5
git checkout v0.3.13
bash install.sh --skip-setup
iva restart

--skip-setup 可避免在已正常運作的 .env 上再次執行精靈。之後執行 iva version，確認最後使用的 commit。

精靈精靈的 5 個步驟，以及各步驟要求的金鑰

1. 模型供應商與模型。MODEL_PROVIDER 接受 opencode、ollama、openrouter 或 codex。精靈會即時驗證金鑰，並列出你的方案可用的模型。
2. 語音與搜尋。Deepgram 金鑰用於轉錄語音記事。網頁搜尋金鑰（Tavily、Exa、Parallel 或 Brave）為選用項目。
3. 來自 @BotFather 的 Telegram bot token，並透過 getMe endpoint 進行檢查。
4. 存取控制。你要傳送訊息給 bot，精靈會從 getUpdates 讀取你的數字 user ID。
5. 系統設定。包括 IANA 時區、vault 目錄，以及本機埠號；預設為 8723。

其中兩項相依服務被「一個指令」的說法掩蓋了。Iva 不內建模型，因此在回答任何內容前，需要付費模型方案或 API key。Iva 也不會自行轉錄音訊，因此語音記事需要額外的服務。Deepgram 的 nova-3 模型搭配 DEEPGRAM_LANGUAGE=multi 可偵測語言，而新的 Deepgram 帳戶會取得 starter credits，足以支應數個月的個人使用。文字功能只需要模型金鑰。只有語音功能依賴 Deepgram。

請檢查精靈寫入的內容。

grep -E '^(MODEL_PROVIDER|TELEGRAM_ALLOWED_USER_IDS|ASSISTANT_VAULT_DIR|IVA_PORT)=' ~/iva/.env
ls -l ~/iva/.env

ls 應顯示 -rw-------，模式為 0600，因為該檔案包含你剛才貼上的所有金鑰。TELEGRAM_ALLOWED_USER_IDS 必須包含你的數字 ID。allowlist 採取 fail closed 設計，因此空值表示 Iva 不會回應任何人。

模型只會在程序啟動時讀取一次。編輯 MODEL_PROVIDER 或 .env 中的模型名稱，在執行 iva restart 前都不會生效。在 openrouter 中，模型名稱是類似 anthropic/claude-sonnet-4.5 的 vendor slug，而不是單純的名稱。在 codex 中，完全沒有 API key：iva login 會登入現有的 ChatGPT 訂閱。

Iva 每月的執行成本是多少

[
  {
    "plan": "Small VPS, always on",
    "usd_per_month": 5
  },
  {
    "plan": "OpenCode Go model plan",
    "usd_per_month": 10
  },
  {
    "plan": "Ollama Cloud model plan",
    "usd_per_month": 20
  },
  {
    "plan": "Deepgram voice, starter credits",
    "usd_per_month": 0
  },
  {
    "plan": "Tavily web search, free tier",
    "usd_per_month": 0
  },
  {
    "plan": "Cheapest complete setup",
    "usd_per_month": 15
  }
]

以下是截至 2026 年 10 月公布的牌價，不是實測結果。小型 VPS 每月 5 美元，加上每月 10 美元的 OpenCode Go 方案，是最便宜的完整配置，每月約 15 美元。OpenCode 的 Go 頁面列出的就是這個月費，且首月沒有折扣；Iva 的 README 則表示，這套配置的總成本約為每月 14 至 15 美元。Ollama Cloud 是另一個固定費率選項，Pro 方案每月 20 美元；超過方案所含額度的用量會另外計費。Voice 在 Deepgram 的入門額度用完前，每月成本為 0。

這裡沒有列出 OpenRouter，因為它採用隨用隨付，帳單會依用量計算。這是需要特別留意的選項：如果助理在每次對話中都使用 131072 token 的上下文視窗，費用可能很快超過固定費率方案。請將上下文視窗變數設為模型的實際大小，因為設定過大的值只會浪費 token。

兩個服務與兩個計時器

• iva.service 執行 agent 本身。
• iva-telegram-poll.service 執行與 Telegram 通訊的 long polling bridge。
• iva-memory-doctor.timer 於 05:00 觸發，對 vault 執行每晚維護作業。
• iva-update-check.timer 於 10:00 觸發，檢查是否有較新的 release。
• iva-telegram-userbot.service 只有在設定選用的 Telethon proxy 時才會存在。

iva status
systemctl --user status iva.service iva-telegram-poll.service
systemctl --user list-timers
iva logs poll

iva status 顯示兩個服務與兩個 watchdog 計時器的狀態。systemctl --user list-timers 顯示每個計時器的下次執行時間，可藉此確認 memory doctor 今晚確實會執行。兩個服務都應處於 active (running)。如果其中一個服務不斷重新啟動，journalctl --user -u iva.service -n 100 會提供原因。

除錯時，這種拆分很重要。bridge 可能仍在執行並持續 polling，但 agent 已停止。此時 Telegram 會接受你的訊息，卻永遠沒有回應。iva logs poll 監控 bridge，iva logs 監控 agent，因此兩份日誌能指出故障位於哪一部分。

Obsidian vault 的位置與備份方式

ASSISTANT_VAULT_DIR 預設位於安裝目錄中的 vault，因此記憶資料位於 ~/iva/vault。它是獨立的 git repository，與程式碼分開，因此更新 Iva 時不會影響你的筆記。

• vault/CORE.md 儲存持久事實與固定偏好，上限為 1200 個字元，並會放入每次 system prompt。
• vault/daily/YYYY-MM-DD.md 是當天的逐字記錄，採附加寫入方式處理。
• vault/cards/ 儲存聯絡人、專案、決策、想法與筆記的型別化卡片。
• vault/summaries/daily/、weekly/、monthly/ 與 yearly/ 儲存彙總資料。
• vault/attachments/ 依日期儲存檔案，vault/.graph/ 儲存連結圖。
• vault/schema.json 定義卡片類型與衰減規則。

彙總作業會在程序內依排程執行。每日 04:00 的作業會將前一天的逐字記錄轉換成卡片與摘要，並重寫 CORE.md；接著每週、每月與每年的作業會依序壓縮這些資料。05:00 時，memory doctor 會執行不涉及 model 的確定性處理：強制套用 schema、重建連結圖、重新產生索引，然後提交並推送。

這次 push 就是你的備份，也是最容易被忽略的步驟。如果 vault 沒有 git remote，doctor 會透過 gh 嘗試建立 private GitHub repository；這需要已完成驗證的 GitHub CLI。

gh auth login
systemctl --user start iva-memory-doctor.service
cd ~/iva/vault && git log --oneline -3

提交日期為今天，表示該次作業已執行且 vault 已完成提交。日誌中的 gh not available 警告則表示相反情況：vault 雖然有維護，卻從未離開伺服器，因此 VPS 故障時，記憶資料也會一併遺失。

也請保留一份由你自行控制的副本。

tar czf ~/iva-vault-backup.tgz -C ~/iva vault

使用 scp 將該檔案複製到伺服器外部，然後從伺服器刪除它。若要在 Obsidian 中讀取記憶資料，請將 Obsidian 指向 vault repository 的 clone。Wikilinks、backlinks 與 graph view 都會照常運作。手動編輯卡片與 CORE.md 是安全的。請勿修改 MOC.md 與 .graph/，因為 nightly pass 會重新產生這兩者。

將 vault 視為生活日誌

該目錄是在你租用的機器上，記錄你說過的話、見過的人以及做過的決定，並依日期整理。這會帶來兩個結論。

Self-hosting 只會移動儲存位置，不會移動處理流程。每次對話都會傳送給你的模型供應商，每段語音筆記都會傳送給 Deepgram。vault 屬於你，但處理請求的公司仍能看見這些內容。自行執行記憶層也是同樣的情況，例如在自己的 VPS 上執行 Mem0 記憶伺服器：儲存內容位於本機，但模型呼叫仍會離開你的環境。如果某個主題敏感到不適合交給第三方，就不要放進聊天內容。

該帳戶能接觸整個 vault。Iva 的工具透過 Node 的 fs 和 child_process 原生在主機上執行，不使用 Docker 或 sandbox，因此遭劫持的對話回合會擁有服務帳戶可用的所有權限。這就是為什麼安裝完成後，該帳戶不保留任何 sudo，也說明了為什麼應更加重視 allowlist，而不是低估它的重要性：它是決定哪些人的訊息能在伺服器上成為命令的閘門。如果你想隨身使用助理，又不想開放任何連入通道，這與 從手機連線到自行託管的 Hermes agent 使用的是同一種模式；此時由聊天用戶端執行原本必須由公開端點負責的工作。

會發生什麼問題，以及你會看到的訊息

組建遭終止，結束碼為 137。 kernel 的 out of memory killer 終止了組建程序。安裝程式只有在 RAM 少於 1.5 GB 且不存在 swap 時才會加入 swap，因此請自行加入 swap，然後重新執行安裝程式。

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
free -h

Failed to connect to bus。 每個 systemctl --user command 都會在 shell 沒有 user session bus 時顯示這個訊息，而 sudo -iu iva 會提供該 bus。請以該使用者開啟一般 SSH session，或在執行 command 前先 export XDG_RUNTIME_DIR=/run/user/$(id -u iva)。

Bot 不回應。 TELEGRAM_ALLOWED_USER_IDS 為空，且 allowlist 採 fail closed。請傳送一則訊息給 Bot；它會回覆你的數字 ID，不會回覆其他內容。將該 ID 放入 .env，然後執行 iva restart。

Bot 在 iva config 後立即停止回應。 wizard 可能會移動 IVA_PORT，但未更新 ASSISTANT_HOST，因此 bridge 會連線到沒有任何程序回應的連接埠。請比對這兩行，然後重新啟動。

grep -E '^(IVA_PORT|ASSISTANT_HOST)=' ~/iva/.env
iva restart

語音訊息沒有回覆。 Telegram Bot API 拒絕下載超過 20 MB 的檔案，因此 bridge 收不到較長的音訊，也沒有內容可傳送給 Deepgram。請在傳送前分割檔案。

ffmpeg -i long.ogg -f segment -segment_time 600 -c copy part-%02d.ogg

對話輪次卡住且沒有回覆。 卡住的 workflow state 會在重新啟動後保留並再次排入佇列，因此單獨重新啟動無法清除它。iva reset 會隔離該 state，並重新啟動兩個服務。在 chat 中輸入 /new 可開始新的對話。

Chromium 在 Ubuntu 24.04 上失敗。 Ubuntu 24.04 透過 AppArmor 封鎖無特權 user namespace，因此 Chromium 自身的 sandbox 無法啟動，agent-browser 也會失敗。安裝程式會將 "--no-sandbox" 寫入 ~/.agent-browser/config.json，以避開此限制。請確認這項設定確實存在。它會降低瀏覽器的隔離程度，因此該帳號更應只擁有 Iva 所需的內容。

FAQ

我需要網域或開放連接埠才能自行託管 Iva 嗎？

不需要。Iva 透過長輪詢與 Telegram 通訊：iva-telegram-poll.service 呼叫 getUpdates 並等待，因此每個連線都是由伺服器對外建立。外部不需要連入這台伺服器，因此不需要 DNS 記錄或憑證。代理程式自己的 HTTP 連接埠 8723 會繫結至 127.0.0.1，而專案文件也要求不要將其公開。防火牆只允許 SSH、拒絕其他所有流量，才是正確設定。

每月執行 Iva 的成本是多少？

依據 2026 年 10 月公布的牌價，小型 VPS 每月 5 美元，加上最便宜的固定費率模型方案每月 10 美元，合計約為每月 15 美元。改用 Ollama Cloud 則為 20 美元，超過包含額度的用量另行計費。Deepgram 的入門額度起初足以支應語音功能，網路搜尋方案也提供免費額度。OpenRouter 採用隨用隨付，因此沒有固定的每月費用。

Iva 將資料儲存在哪裡？如何備份？

預設儲存在 ~/iva/vault，由 ASSISTANT_VAULT_DIR 設定。這是一個獨立的私有 git repository，內容為純 markdown：CORE.md、daily/YYYY-MM-DD.md、cards/ 和 summaries/。05:00 執行的 memory doctor 會將其提交並推送；但只有 repository 設定了 remote 時才有效，因此請執行 gh auth login，或在設定期間自行新增 remote。也請使用 tar czf ~/iva-vault-backup.tgz -C ~/iva vault 保留離線副本，並將該檔案移出伺服器。

自行託管 Iva 時，我的資料是私密的嗎？

儲存空間由你掌控，但處理資料的服務不是。vault 在你推送前會留在自己的磁碟上，而 .env 的模式為 0600，擁有者是服務使用者。模型呼叫與語音轉錄使用雲端 API，因此這些訊息會經過你的模型供應商和 Deepgram。Iva 採用 MIT 授權，因此你可以確實查看它傳送的內容並加以修改。Telegram allowlist 採用預設拒絕策略，也就是空白的 TELEGRAM_ALLOWED_USER_IDS 會封鎖所有人，包括你自己。

Iva 支援哪些模型供應商？

在固定的 v0.3.13 版本中，MODEL_PROVIDER 接受 opencode（OpenCode Go）、ollama（Ollama Cloud）、openrouter 和 codex。OpenRouter 使用例如 anthropic/claude-sonnet-4.5 的供應商 slug，並提供最廣泛的模型選擇。codex 會透過 iva login 登入現有的 ChatGPT 訂閱，且不使用 API key。後續版本會新增更多路由，包括 Claude 訂閱和自訂的 OpenAI 相容端點。設定供應商後，將相符的 context window 設為模型的實際大小，接著執行 iva restart，因為模型只會在程序啟動時讀取一次。