快速开始

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 里