Notion CLI 怎麼用？從 ntn login 到 Workers 部署前的權限檢查

2026-08-12

工具推薦

AI

/

/

/

/

Notion CLI（指令名稱是 ntn）適合把 Notion 操作放進終端機與開發工作流。它不只是 API request 的包裝，也能在有權限的前提下建立、部署和管理 Notion Workers；這讓 coding agent 或 CI workflow 可以少一層手動切換瀏覽器的步驟。

但 CLI 能安裝，不等於目前登入的 workspace 就能部署 Workers。Notion 官方 Help Center 把這幾件事分開：CLI 本身所有方案都能使用；Workers 的部署與管理需要 Business 或 Enterprise，某些 developer platform 功能還要 workspace owner 開啟。先做權限檢查，再跑 deploy，會比看到錯誤後才猜帳號問題省時間。

先分清楚 CLI、Notion API 與 Workers 的邊界#

入口	能做什麼	先確認的條件
Notion CLI `ntn`	在終端機登入、讀寫內容與發送 API request	目前登入的帳號和 workspace
Notion API	依 token 與頁面／資料庫權限讀寫資料	目標頁面或 data source 已分享給整合
Notion Workers	在 Notion infrastructure 背景執行 sync、tool 或 webhook	Business／Enterprise 與 workspace Workers 權限
Custom Agents 呼叫 Worker	讓 agent 把固定步驟交給程式執行	Agent、Worker、credits 與資料來源權限

這個分層很重要：ntn login 成功，只代表 CLI 已連到一個 Notion workspace；它不代表你可以讀取所有頁面，也不代表 Workers 已啟用。Notion Help Center 也明確說，CLI 能不能讀寫某一頁，仍取決於你在 Notion 介面中是否有該頁面的存取權。

安裝 Notion CLI 並登入#

Notion 官方目前提供 npm 安裝方式，CLI 可在 macOS、Linux 和 Windows 使用：

1
npm install -g ntn
2
ntn --version
3
ntn login

ntn login 會開啟瀏覽器完成授權，登入憑證會由作業系統的 keychain 保存。第一次登入後，先不要直接建立 Worker；先確認 terminal、瀏覽器和 Notion 使用的是同一個帳號，尤其是你同時有個人 workspace、公司 workspace 或多個企業帳號時。

如果你偏好官方 developer docs 的 bootstrap script，也可以先查看文件提供的安裝選項；正式環境仍建議在 CI 或開發機記錄 ntn --version，避免不同成員使用不同 CLI 版本時得到不一致結果。

最小 Workers 指令流程#

Notion Developer Docs 的入門頁列出下面這組核心指令：

1
ntn workers new
2
ntn workers deploy
3
ntn workers list

可以把它理解成三個階段：

workers new 建立一個 Worker 專案骨架。
workers deploy 建置並上傳 Worker。
workers list 查看目前 workspace 已部署的 Workers。

正式執行 deploy 前，先在專案中確認 Worker 會讀寫哪些 Notion page、database 或 data source，以及會呼叫哪些外部 API。Worker 是背景程式，不會因為放在 Notion 裡就自動取得所有 workspace 資料；權限仍應以最小範圍設定。

部署前的四項檢查#

1. 確認 workspace 和帳號#

先在瀏覽器確認目前 workspace，再從 CLI 完成登入。若登入過多個帳號，遇到「看不到頁面」時，先登出並重新登入正確帳號，不要立刻重建 Worker。

2. 確認頁面與資料來源權限#

在 Notion 中打開 Worker 將使用的頁面、資料庫或 data source。如果你在介面中就沒有讀取權限，CLI 不會替你繞過這個限制。要寫入資料時，也要把寫入權限和讀取權限分開盤點。

3. 確認 Workers 計畫與 workspace 開關#

Notion 官方說明 CLI 對所有 plan 可用，但部署和管理 Workers 需要 Business 或 Enterprise；Workers 還可能受 workspace owner 的開關控制。若 ntn workers deploy 失敗，先確認方案與 Workers 是否被啟用，再處理程式本身。

4. 確認用量和資料邊界#

Workers 適合執行不需要 AI reasoning 的固定工作，例如同步資料、寫入更新與處理事件。若 Worker 會被 Custom Agent 反覆呼叫，執行次數、外部 API 和寫入量都要納入預估；不要把 Worker 當成沒有成本的無限 webhook。

截至 2026 年 8 月 12 日，我查到的 English (US) Notion Help Center 仍將 Workers 描述為 Business／Enterprise beta 期間可免費試用，並列出後續改以 Notion credits 計算的日期。這類 beta 與 credits 條件可能依 workspace 和官方文件更新，實際導入前應再看 Settings → Access & billing → Notion credits，以及 Worker 是否顯示 Free badge、runs 和 credits 使用量。

用量檢查比「能不能 deploy」更早#

一個每 15 分鐘執行的同步 Worker，和每天執行一次的 Worker，對 workspace 的 runs 完全不是同一種負擔。正式導入前可以先寫下：

觸發來源：排程、Custom Agent tool call 或 webhook。
每日預估 runs，以及失敗重試可能增加的次數。
每次執行會讀取和寫入哪些資料。
是否能先批次處理，而不是每一筆變更觸發一次 Worker。
哪些資料需要留在 Notion，哪些只需傳給外部 API。

官方 pricing 說明也提供 ntn CLI 和 Notion credits dashboard 的用量觀察方式。先讓同步頻率從每日或每小時開始，再依實際資料需求提高頻率，比一開始就用每分鐘觸發更容易預估。

和 Notion External Agents 怎麼搭配#

如果你已經在使用 Notion 3.6 External Agents 的工作流，可以把角色分開：External Agent 負責判斷下一步，Worker 負責執行固定、可重跑的資料同步或 API 呼叫。這樣 agent 不必直接擁有所有資料寫入能力，Worker 的輸入、輸出與錯誤處理也比較容易測試。

相反地，如果任務每次都需要不同的推理、需要人類確認，或資料來源權限尚未釐清，就不要為了「可以用 CLI」而急著把它包成 Worker。先把讀取、判斷、寫入三個步驟拆開，才能知道哪一段應由 agent、哪一段應由固定程式負責。

常見問題#

Q: Notion CLI 所有方案都能安裝嗎？#

A: 官方 Help Center 表示 CLI 可在所有方案使用，但部署與管理 Notion Workers 需要 Business 或 Enterprise；部分 developer platform 功能也可能需要 workspace owner 開啟。安裝成功和可以 deploy 是兩個不同檢查。