openClaw 와 notion 연동하기 : Skill 직접 만들기
openClaw 와 notion 연동하기.
openclaw hub에 가면 노션 스킬을 구할 수 있는 것으로 안다.
그런데 이 곳에서 다운 받는 스킬은 안심할 수 없다.
아무리 Mac이 보안에 진심이라해도,
출처를 알 수 없는 스킬을 다운받아서 에이전트에게 돌리라고 하기엔
너무 위험 부담이 크다. 프로그램에 뭘 숨겨놨을지 누가 알랴?
그래서 직접 필요한 Skill은 직접 만들어서 사용하면 된다.
스킬 만드는게 그리 어렵지 않다.
전에 searXNG 도 오픈클로에서 툴도 지원안되고, 스킬도 지원 안되서
그냥 직접 Skill 만들어서 연결했었다.
한 번 만들어보자.
1. 사전 준비: Notion API 설정
먼저 Notion과 통신하기 위한 권한이 필요합니다.
- 통합(Integration) 생성: Notion My Integrations에서 새 통합을 만들고 Internal Integration Token을 복사하세요.
- 권한 공유: 사용하려는 Notion 페이지나 데이터베이스 오른쪽 상단의 ... 버튼 → 연결 추가(Add connections)에서 방금 만든 통합을 선택해 공유해야 합니다.
1) 본인 노션 : 좌측 상단 자신의 아이콘, 아이디 옆 화살표 누르면 아래에 '설정'
좌측 메뉴에서 '연결' 누른 후, 'API연결 개발 또는 관리' 누릅니다
**혹은 아래 페이지로 바로 이동해도 됩니다.
https://www.notion.so/profile/integrations/public
The AI workspace that works for you. | Notion
Build Custom Agents, search across all your apps, and automate busywork. The AI workspace where teams get more done, faster.
www.notion.com
좌측 메뉴 하단 'Internal integrations' 선택
- 새 API 통합 만들기 +버튼 클릭!
- 여기서 개인(혼자 사용하는 분)은 이걸 선택해야지, 그 위에 있는'API 통합' 메뉴를 선택하지 않습니다. (주의)
- 회사나 그룹이 사용할 경우 위의 'API통합' 메뉴를 선택합니다.
'API 통합 이름'을 입력하고, 관련 워크스페이스를 클릭하면 본인 노션을 선택할 수 있습니다.
다음 '생성하기' 누르면 됩니다
기능에서 체크된 부분 확인합니다.
프라이빗 API 통합 시크릿 부분의 '표시하기' 버튼을 누르면 키가 보여지고, '복사'버튼이 활성화 되며, 눌러서 복사해둡니다
2) 본인 노션 중 하나의 페이지를 선택하고 우측 펼침메뉴버튼(점세개) 클릭
(오픈클로 에이전트에게 공유할 노션 페이지를 미리 하나 만듬)
하단의 '연결' 누르고 리스트에서 아래로 내리다보면 좀전에 만든 자신의 api 이름이 뜰것이다.
선택하면 연결된다.
이제 노션에서 할 일은 끝났다.
만든 키 잘 보관해두고 나중에 오픈클로에게 주입하자.
이제 스킬을 만들 차례...
2. 스킬 구조 만들기
OpenClaw 스킬은 보통 ~/.openclaw/skills/ 폴더 내에 위치합니다.
터미널에 아래와 같이 입력하고 실행해주면, 해당위치에 노션 스킬 폴더와 SKILL.md 파일까지 생성됩니다.
mkdir -p ~/.openclaw/skills/my-notion-skill
cd ~/.openclaw/skills/my-notion-skill
touch SKILL.md
3. SKILL.md 작성 (핵심 로직)
SKILL.md는 에이전트에게 이 스킬을 어떻게 사용하는지 가르치는 설명서입니다.
직접 코드를 짜기보다 cURL 명령어 패턴을 알려주어 에이전트가 직접 실행하게 하는 것이 가장 빠릅니다.
SKILL.md 파일을 열어서 아래 내용을 입력 후 저장!
---
name: my-notion-skill
description: Notion 페이지 읽기, 쓰기 및 생성을 위한 스킬
metadata:
requires:
env:
- NOTION_API_KEY
- NOTION_DEFAULT_PAGE_ID
---
# Notion 스킬 가이드
너는 Notion API를 사용하여 사용자의 워크스페이스를 관리한다. 모든 요청은 `curl`을 사용하며, 아래 정보를 반드시 포함해야 한다.
- **Base URL:** `https://api.notion.com`
- **Headers:**
- `Authorization: Bearer $NOTION_API_KEY`
- `Notion-Version: 2022-06-28`
- `Content-Type: application/json`
**기본 작업 페이지 ID:** `$NOTION_DEFAULT_PAGE_ID`
사용자가 특정 페이지를 언급하지 않으면 위 ID를 부모(parent)로 사용하여 새 페이지를 생성하거나 글을 써라.
## 1. 페이지 생성 (Create)
- **Method:** POST
- **URL:** https://api.notion.com/v1/pages
- **Body Example:**
```json
{
"parent": { "page_id": "$NOTION_DEFAULT_PAGE_ID" },
"properties": {
"title": [{ "text": { "content": "제목" } }]
}
}
## 2. 페이지 읽기 (Read)
- **Endpoint:** GET https://api.notion.com/v1/blocks/{page_id}/children
- **내용:** 특정 페이지의 하위 블록(본문 내용)을 가져옵니다.
## 3. 글쓰기/내용 추가 (Write)
- **Endpoint:** PATCH https://api.notion.com/v1/blocks/{page_id}/children
- **내용:** 기존 페이지 끝에 새로운 블록(문단 등)을 추가합니다.
# Notion API 사용 예시
너는 Notion API를 사용하여 사용자의 워크스페이스를 관리한다. 모든 요청은 `curl`을 사용하며, 환경변수 `$NOTION_API_KEY`를 반드시 포함해야 한다.
## 1. 페이지 생성 예시
사용자가 페이지를 만들라고 하면 아래 구조로 요청하라.
- **Method:** POST
- **URL:** https://api.notion.com
- **Header:** `Notion-Version: 2022-06-28`
- **Body Example:**
```json
{
"parent": { "page_id": "부모_페이지_ID" },
"properties": {
"title": [{ "text": { "content": "제목" } }]
}
}
## 2. 페이지 읽기 (블록 가져오기) 예시
Method: GET
URL: api.notion.com{block_id}/children
## 3. 내용 추가 (글쓰기) 예시
Method: PATCH
URL: api.notion.com{block_id}/children
Body Example:
json
{
"children": [
{ "object": "block", "type": "paragraph", "paragraph": { "rich_text": [{ "text": { "content": "내용" } }] } }
]
}
4. 환경 변수 등록
먼저 발급받은 노션 API Key 와 사용할 노션 특정 페이지의 Page ID 를 보관할 곳을 만듭니다.
오픈클로 루트에 .env 파일을 만들고 아래와 같이 넣어줍니다 (본인 키와 페이지 아이디)
API Key 에는 특수문자가 들어감으로, 일자형 따옴표(하나짜리) ' 요걸 양쪽에 써야합니다.
꼭 반드시 이거 때문에 수없는 삽질. (사람들이 잘 모르는 사실)
- 그리고 요즘은 key에 프리픽스로 ntn_ 붙어서 나옵니다. 그대로 넣어주시면 됩니다.
- 페이지 id는 숫자와 알파벳으로 이뤄진 32자의 문자열입니다. 그대로 넣어주시면 됩니다.
NOTION_API_KEY='ntn_xxxxxxxxxxx'
NOTION_DEFAULT_PAGE_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
openclaw.json 설정 파일에 아래 코드를 추가해줍니다 Tools 아래에 열을 맞춰서 추가해줍니다 (동일한 위상)
"tools": {
"sessions": {
"visibility": "all"
},
"agentToAgent": {
"enabled": true
},
"subagents": {
"tools": {
"deny": [
"gateway",
"cron"
]
}
}
},
"skills": {
"entries": {
"my-notion-skill": {
"enabled": true,
"env": {
"NOTION_API_KEY": "secret_your_token_here"
}
}
}
},
5. 실행 및 테스트
OpenClaw를 재시작한 후, 채팅창에 다음과 같이 요청해 보세요.
"노션 연결했는데 접속해서 새페이지 만들고 오늘 한 일 올려봐."
에이전트는 정의된 SKILL.md를 참고하여 curl 명령어를 조합해 Notion API를 호출하게 됩니다.
아래 흐름을 보면 Skill 파일을 읽고, 환경설정읽어서 키를 확인하고, 노션에 글을 올린다.
(.config/api-key 에도 같은 키가 들어있었다. 이건 테스트용이었으므로 나중에 삭제했음)
몇 번의 뻘짓 끝에 성공했음.
노션 해당 페이지에 잘 작성되었음
노션에 쓰여있는 글을 읽어와보라고 시켜봄
> 오늘 한 일, 잘 읽어옴.
별 것도 아닌 것인데, API key 에러라고 떠서 검색만 엄청하고,
ai 한테도 엄청 물어보고,,, 반나절이 다 지나갔음.
마지막 제미나이 형님이 따옴표를 지적해줬음. ㅎㅎ
암튼 쉽게 되는게 없네요.
혹시 한번에 성공하지 못하고 아래와 같은 오류를 남발한다면...
'API 토큰(NOTION_API_KEY)이 유효하지 않다는 오류(401 Unauthorized)가 발생'
에이전트한테 아무리 떠들어봐야 안됩니다. 못합니다.
그냥 먼저 터미널에서 테스트한 후 성공하면 적용하는 방법으로 합니다.
완벽한 성공 팁 :
터미널에서 테스트하는 방법 - 성공한 케이스 (위에 보면 '맥 터미널에서 보낸 메시지!' 이 코드로 성공한 것임)
절대 띄어쓰기와 따옴표와 슬래시와 역슬래시 매우 주의해야함!
키를 못 읽는다고 에러가 뜨는 원인의 대부분은 실제로 키값에 문제가 있는 것이 아니며, 양식에 문제가 있는 것임
위에서 .env 내용이 잘 못 적힌 경우가 대부분. 특히 일자형 따옴표 때문에 에러가 날 줄은 상상 못했음.
그리고 secret_ 프리픽스도 한 몫 했음.
노션 페이지 읽기
curl 'https://api.notion.com/v1/blocks/xxxxxxxxxx817bf4bxxxxxxxxx/children' \
-H 'Authorization: Bearer ntn_xxxxxxxxxxxxxxxxxxmwBdgPmUmrbixxxxxxxxxxxxxxxx' \
-H 'Notion-Version: 2022-06-28'
노션 페이지 쓰기
curl -X PATCH 'https://api.notion.com/v1/blocks/xxxxxxxxxxxxx0b9817bxxxxxxxxxxxx/children' \
-H 'Authorization: Bearer ntn_xxxxxxxxxxxxxxxxxxxxBdgPmUmrbixuxxxxxxxxxxxxxx' \
-H 'Content-Type: application/json' \
-H 'Notion-Version: 2022-06-28' \
--data '{
"children": [
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [{ "type": "text", "text": { "content": "맥 터미널에서 보낸 메시지! 🚀" } }]
}
}
]
}'
실패 메시지 예시
{"object":"error","status":401,"code":"unauthorized","message":"API token is invalid.","request_id":"xxxxxxxx-xxxx-xxxx-xxxxxxxxx"
성공 메시지 예시
페이지 읽기에 성공시 >>>> 거의 한페이지 짜리 장문이 출력되면 성공
{"object":"list","results":[{"object":"block","id":"xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"parent":{"type":"page_id","page_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},
"created_time":"2026-02-26T05:35:00.000Z","last_edited_time":"2026-02-26T05:35:00.000Z",
"created_by":{"object":"user","id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"......
페이지 쓰기에 성공시 >>>> 아래처럼 중간에 문장이 출력되고, 노션 페이지에도 작성된 것을 확인할 수 있음 (위 참조)
{"object":"list","results":[{"object":"block","id":"xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"parent":{"type":"page_id","page_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},
"created_time":"2026-02-26T07:05:00.000Z","last_edited_time":"2026-02-26T07:05:00.000Z",
"created_by":{"object":"user","id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},
"last_edited_by":{"object":"user","id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},
"has_children":false,"archived":false,"in_trash":false,"type":"paragraph","paragraph":
{"rich_text":[{"type":"text","text":{"content":"맥 터미널에서 보낸 메시지! 🚀","link":null},
"annotations":{"bold":false,"italic":false,"strikethrough":false,"underline":false,
"code":false,"color"
BR.h