快速開始

Worker 讓 Custom Agent 突破 Notion 生態的邊界，透過你自己撰寫的程式碼去呼叫任意外部 API。本篇帶你從零搭建環境、建立第一個 Worker、部署到 Notion 並完成測試。

Worker vs MCP

在動手之前，先搞清楚 Worker 和 MCP 的區別：

• MCP 是「用別人搭好的橋」。Notion 官方預置了 Stripe、GitHub、Figma 等十幾個 MCP 伺服器，點幾下就能接入，但你只能使用別人定義好的工具
• Worker 是「自己造一座橋」。你用程式碼定義工具的行為，精確控制發什麼請求、傳什麼參數、怎麼處理回傳結果

簡單來說：MCP 覆蓋不到的場景，Worker 來補。如果你想了解 Worker 的實際應用效果，可以看看這篇實踐記錄。

環境準備

Worker 開發需要以下環境：

• Node.js >= 22
• npm >= 10.9.2
• Notion 商業版會員（Worker 功能需要商業版權限）

確認環境後，安裝 Notion CLI：

npm i -g ntn

然後登入你的 Notion 工作區：

ntn login

建立第一個 Worker

Notion 官方提供了一個模板倉庫，先把它複製到本地：

npx degit makenotion/workers-template my-worker
cd my-worker
npm install

打開 src/index.ts，你會看到專案的核心檔案結構很簡單：

import { Worker } from "@notionhq/workers";

const worker = new Worker();
export default worker;

worker.tool("sayHello", {
  title: "Say Hello",
  description: "Return a greeting",
  schema: {
    type: "object",
    properties: {
      name: { type: "string" }
    },
    required: ["name"],
    additionalProperties: false
  },
  execute: ({ name }, _context) => `Hello, ${name}`,
});

這就是一個最小的 Worker。它只做一件事：接收一個名字，回傳一句問候語。

每個 tool 就是 Agent 可以呼叫的一個工具，其中：

• title 和 description 會顯示在 Notion Agent 的工具列表裡，同時也是 Agent 理解這個工具用途的依據
• schema 定義了 Agent 呼叫時必須提供的參數（JSON Schema 格式）
• execute 是實際執行的邏輯

部署

寫好程式碼後，一行命令即可部署：

ntn workers deploy

部署完成後，這個 Worker 的工具會自動出現在你 Notion 工作區的 Custom Agent 工具列表中。

如果 Worker 需要用到 API 金鑰等敏感資訊，透過環境變數設定：

ntn workers env set API_KEY=your-api-key

在程式碼中透過 process.env.API_KEY 讀取。

測試

部署後可以直接在命令列測試工具是否正常運作：

# 測試已部署的遠端 Worker
ntn workers exec sayHello -d '{"name": "World"}'

# 本地測試（不需要先部署，.env 文件會自動載入）
ntn workers exec sayHello --local -d '{"name": "World"}'

本地測試非常適合開發階段快速迭代，改完程式碼直接跑，不用每次都部署。

OAuth 接入

如果你的 Worker 需要代表使用者存取第三方服務（比如發推特、操作 GitHub），就需要設定 OAuth：

const myOAuth = worker.oauth("myOAuth", {
  name: "my-provider",
  authorizationEndpoint: "https://provider.example.com/oauth/authorize",
  tokenEndpoint: "https://provider.example.com/oauth/token",
  scope: "read write",
  clientId: "your-client-id",
  clientSecret: process.env.MY_OAUTH_SECRET ?? "",
});

部署帶有 OAuth 的 Worker 後，還需要設定第三方平台的回呼地址。執行以下命令取得 Notion 分配的回呼 URL：

ntn workers oauth show-redirect-url

然後把這個 URL 填入第三方平台的 OAuth 應用設定中。

除錯

Worker 部署後，可以透過 ntn workers runs 查看執行歷史和日誌：

# 列出最近的執行記錄
ntn workers runs list

# 查看某次執行的詳細日誌
ntn workers runs logs <runId>

# 快速查看最新一次執行的日誌
ntn workers runs list --plain | head -n1 | cut -f1 | xargs -I{} ntn workers runs logs {}

--plain 參數會輸出純文字格式，方便用管道命令做進一步處理。

如果需要排查 CLI 設定問題，可以執行：

ntn debug

功能可用性

Worker 目前處於 Alpha 階段，各功能的開放狀態如下：

• ✅ Agent 工具（Tools） — 已公開，正是本文介紹的核心功能
• ✅ OAuth（使用者管理） — 已公開，用於接入需要授權的第三方服務
• 🔧 OAuth（Notion 管理） — 內測中
• 🔧 Syncs（資料同步） — 內測中
• 🔧 Automations（自動化） — 內測中

Alpha 階段 Worker 免費使用，正式版的計費策略尚未公佈。

下一步

環境搭好、基礎概念理解之後，你可以：

• 閱讀 Worker 實踐：部落格自動發佈，看一個完整的實戰案例
• 嘗試把你常用的第三方 API 封裝成 Worker 工具
• 在 Custom Agent 文件 中了解如何將 Worker 工具設定到 Agent 裡