라즈베리파이5 AI 머신 세팅 6: Hermes Notion API 연결과 읽기·쓰기 검증

5편에서는 Google Cloud OAuth 클라이언트를 만들고 Gmail·Calendar·Drive·Sheets·Docs·Contacts를 Hermes에 연결했습니다. 이번에는 같은 라즈베리파이5 AI 머신에서 회사 Notion의 업무 페이지를 검색하고 읽고, 승인받은 범위 안에서 새 페이지를 만드는 연결을 추가합니다.

아직 5편을 완료하지 않았다면 아래 글부터 진행하세요.

라즈베리파이5 AI 머신 세팅 · 5편 Hermes Google OAuth 연결 Google API 6개 활성화부터 OAuth JSON 전송, 브라우저 승인과 실제 API 호출 검증까지 먼저 진행합니다. 5편 먼저 보기 →

이번 6편에서 진행할 것

1. Notion Developer Portal에서 신규 내부 연결을 만듭니다.
2. 회사 워크스페이스라면 Workspace Owner에게 생성을 요청합니다.
3. 콘텐츠 읽기·업데이트·삽입 권한을 설정합니다.
4. 업무 페이지를 Integration의 Content access에 추가합니다.
5. Internal Integration Secret을 라즈베리파이의 ~/.hermes/.env에 저장합니다.
6. Hermes에게 공식 ntn CLI 인증과 페이지·데이터베이스 읽기 검증을 요청합니다.
7. 생성할 테스트 내용을 먼저 확인한 뒤 페이지 하나를 만듭니다.
8. Gateway를 재시작해 새 환경변수를 반영합니다.

핵심은 토큰 하나를 복사하는 일이 아닙니다. Integration 권한, 공유된 페이지 범위, 서버의 secret 보관, 읽기 우선 검증, 승인 후 쓰기를 각각 나눠 확인해야 합니다.

보안 주의: Notion Integration Token은 비밀번호처럼 취급합니다. Slack 스레드, Discord 채널, Git 저장소, 블로그 캡처에 붙여 넣지 마세요. 화면에서 가렸더라도 실제 값이 이미 공유됐다면 해당 연결에서 토큰을 재발급하고 Hermes 환경 파일도 새 값으로 교체해야 합니다.

시작 전 준비 사항

• 5편까지 완료한 Raspberry Pi 5와 실행 중인 Hermes Gateway
• 라즈베리파이에 SSH로 접속할 수 있는 PC
• 연결할 Notion 워크스페이스와 업무 페이지
• 회사 워크스페이스라면 Workspace Owner에게 요청할 수 있는 연락 경로
• 페이지 생성 테스트 전에 결과를 확인하고 승인할 사용자

이번 환경의 Notion 워크스페이스는 회사 전용이었고, 제 계정은 Workspace Owner가 아니었습니다. 그래서 직접 연결을 만들려 할 때 선택 가능한 워크스페이스가 나오지 않았고, Workspace Owner에게 Hermes용 Internal Integration 생성을 요청해 진행했습니다.

1. Notion Developer Portal에서 신규 연결 시작하기

브라우저에서 Notion Integrations에 접속합니다. 현재 화면에서는 왼쪽의 연결 메뉴를 선택한 뒤 오른쪽 위 신규 연결을 누릅니다.

Notion UI의 명칭은 시점에 따라 Integrations, Connections, 연결처럼 다르게 보일 수 있습니다. 중요한 것은 일반 페이지의 공유 메뉴가 아니라 Notion Developer Portal의 내부 연결 관리 화면에서 시작하는 것입니다.

2. 액세스 토큰 방식과 워크스페이스 선택하기

신규 연결 창에서 다음처럼 설정합니다.

• 연결 이름: Hermes처럼 용도를 알아볼 수 있는 이름
• 인증 방법: 액세스 토큰
• 설치 가능한 워크스페이스: Hermes가 접근할 회사 워크스페이스

액세스 토큰 방식은 하나의 워크스페이스에서 자체 업무 자동화에 사용하는 내부 연결입니다. 여러 고객의 워크스페이스에 설치하는 공개 OAuth 앱과 목적이 다릅니다.

회사 워크스페이스가 목록에 나오지 않을 때

Notion 공식 문서상 내부 연결을 만들려면 Workspace Owner여야 합니다. 일반 멤버나 게스트는 설치 가능한 회사 워크스페이스를 선택하지 못할 수 있습니다.

이 경우 개인 워크스페이스에 임의로 만든 뒤 회사 자료를 옮기지 말고, Workspace Owner에게 다음 내용을 전달해 생성을 요청합니다.

Notion 내부 연결 생성 요청

- 연결 이름: Hermes
- 대상 워크스페이스: 회사 업무 워크스페이스
- 인증 방식: 액세스 토큰 / Internal connection
- 콘텐츠 권한: 읽기, 업데이트, 삽입
- 페이지 접근: Hermes가 사용할 업무 페이지와 필요한 데이터베이스만
- 댓글 권한: 현재는 불필요, 자동화가 필요할 때 별도 검토
- 사용자 정보 권한: 이메일 조회가 필요하지 않아 요청하지 않음

관리자에게도 토큰을 Slack 공개 스레드에 붙여 달라고 요청하면 안 됩니다. 연결 생성 뒤 토큰을 안전한 경로로 전달받거나, 관리자가 직접 서버의 secret 저장 절차를 수행하도록 역할을 정합니다.

3. 콘텐츠 권한을 최소 범위로 설정하기

연결이 만들어지면 구성 또는 Capabilities 화면에서 기능을 확인합니다. 이번 연결에서는 다음 세 가지 콘텐츠 권한을 활성화했습니다.

Read content
Update content
Insert content

한국어 화면에서는 다음처럼 표시됩니다.

• 콘텐츠 읽기
• 콘텐츠 업데이트
• 콘텐츠 삽입

페이지를 읽고 새 테스트 페이지를 만들려면 읽기와 삽입 권한이 필요합니다. 기존 페이지 내용을 수정할 계획이라면 업데이트 권한도 필요합니다. 반대로 읽기 전용 요약만 쓸 것이라면 업데이트와 삽입을 끈 별도 Integration을 만드는 편이 더 안전합니다.

댓글과 사용자 정보 권한은 필요한 경우에만

댓글 자동화가 꼭 필요할 때만 다음 권한을 추가합니다.

Read comments
Insert comments

사용자 이메일 조회가 필요하지 않다면 사용자 정보 권한은 사용자 정보 없음으로 둡니다. 권한을 넓혀 두고 나중에 쓰지 않는 것보다, 실제 자동화 요구가 생겼을 때 관리자와 다시 검토하는 편이 안전합니다.

4. Internal Integration Secret 확인하기

같은 구성 화면의 액세스 토큰 또는 Internal Integration Secret 영역에서 복사를 누릅니다. 토큰은 환경과 발급 시점에 따라 보통 다음 접두사 중 하나로 시작할 수 있습니다.

ntn_
secret_

접두사만 보고 정상 여부를 단정하지 말고, 실제 API 인증으로 확인합니다. 토큰 전체는 이 글, 화면 캡처, 셸 기록에 출력하지 않습니다.

노출 대응: 토큰을 Slack이나 Discord에 한 번이라도 올렸다면 메시지를 지우는 것만으로 끝내지 말고 Notion Developer Portal에서 토큰을 재발급하세요. 이전 토큰이 더 이상 작동하지 않는지 확인한 뒤 서버의 환경 파일도 교체합니다.

5. 업무 페이지를 Content access에 추가하기

토큰을 발급받아도 Notion 워크스페이스 전체가 자동으로 공개되는 것은 아닙니다. 내부 연결 편집 화면의 콘텐츠 사용 권한 탭으로 이동합니다.

처음에는 “아직 어떤 페이지에도 접근할 수 없습니다”라는 안내가 보일 수 있습니다. 페이지 추가 또는 편집 권한을 눌러 Hermes가 사용할 페이지와 데이터베이스만 선택합니다.

이번에는 팀스페이스의 업무 페이지 하나와 그 아래에서 테스트할 페이지 범위를 연결했습니다.

페이지 이름을 가린 이유는 회사 내부 정보이기 때문입니다. 독자도 게시용 캡처에서 워크스페이스명, 팀스페이스명, 페이지명, 고객명, 프로젝트명을 함께 확인하세요.

접근 범위 원칙: 상위 페이지를 연결하면 구조에 따라 하위 페이지 접근 범위도 넓어질 수 있습니다. “업무 페이지 전체”를 편의상 연결하기보다 Hermes가 실제로 검색하고 수정해야 할 최소 페이지와 데이터베이스부터 추가하세요.

6. 라즈베리파이의 Hermes 환경 파일에 토큰 저장하기

PC에서 2편에 만든 SSH 별칭으로 라즈베리파이에 접속합니다.

ssh pi-office

Hermes 환경 파일을 엽니다.

nano ~/.hermes/.env

파일 맨 아래에 다음 세 줄을 추가합니다. 첫 번째와 두 번째의 ***에는 동일한 실제 Internal Integration Secret을 넣습니다.

NOTION_API_KEY=***
NOTION_API_TOKEN=***
NOTION_KEYRING=0

• NOTION_API_KEY: Hermes의 Notion Skill과 API 호출에서 사용
• NOTION_API_TOKEN: Notion 공식 ntn CLI가 읽는 환경변수
• NOTION_KEYRING=0: headless 서버에서 OS 키체인 사용을 피하는 설정

nano에서 저장하고 종료합니다.

1. Ctrl+O
2. Enter
3. Ctrl+X

환경 파일은 소유자만 읽고 쓸 수 있도록 권한을 제한합니다.

chmod 600 ~/.hermes/.env

권한만 확인하고 토큰 내용은 출력하지 않습니다.

stat -c '%a %n' ~/.hermes/.env

출력에는 다음 값이 포함되어야 합니다.

600 ~/.hermes/.env

버전과 셸 환경에 따라 다른 정보가 함께 표시될 수 있습니다. cat ~/.hermes/.env나 env | grep NOTION처럼 secret 값을 화면에 출력하는 명령은 게시용 검증에 사용하지 않습니다.

7. API Key 등록 후 Notion 테스트 명령 입력하기

Integration Token을 ~/.hermes/.env에 저장한 뒤, Hermes와 대화하는 제한된 스레드에서 다음 명령을 입력해 실제 연결 테스트를 시작했습니다.

업무 페이지 아래에 테스트 페이지 하나를 만들 계획을 보여줘.
제목, 본문, 부모 페이지를 먼저 적고 내 승인 전에는 생성하지 마.

이 요청은 단순히 페이지 하나를 만들라는 명령이 아닙니다. Hermes가 먼저 제목·본문·부모 페이지를 보여주고 사용자가 확인하기 전에는 Notion에 쓰지 않도록 실행 경계를 정한 요청입니다. 계획을 확인한 뒤 진행을 승인했고, Hermes는 다음 순서로 연결 전체를 시험했습니다.

1. 공식 ntn CLI 설치와 버전 확인
2. 환경변수를 통한 Integration Bot 인증
3. 공유된 업무 페이지 검색
4. 페이지 내용을 Markdown으로 읽기
5. 공유된 데이터베이스 또는 data source 조회
6. 승인된 하위 테스트 페이지 생성
7. 생성된 페이지 재조회

공식 ntn CLI가 설치돼 있다면 Hermes는 NOTION_API_TOKEN을 이용해 브라우저 로그인 없이 headless 서버에서 API를 호출할 수 있습니다. 이번 실제 검증에서는 ntn 0.19.1이 사용됐습니다. 버전은 업데이트 시점에 따라 달라질 수 있으므로 숫자가 정확히 같아야 하는 것은 아닙니다.

8. Hermes의 Notion 연결 검증 결과 확인하기

테스트가 끝난 뒤 Hermes가 반환한 결과가 아래 화면입니다. 이 화면은 페이지를 만들기 전의 계획 화면이 아니라, 인증·검색·읽기·쓰기·재조회까지 모두 끝난 최종 검증 결과입니다.

결과에는 다음 항목이 정상으로 표시됐습니다.

• 공식 ntn CLI 동작
• Integration Bot 인증
• 환경변수 인식
• 공유 페이지 검색
• 페이지 Markdown 읽기
• 하위 페이지 생성
• 생성된 페이지 재조회

테스트로 만들어진 페이지의 제목과 내용도 함께 표시됩니다.

제목: Hermes Notion 연결 테스트 - 2026-07-21
내용:
- 서버: pi-office
- 상태: 연결 테스트 성공

Notion API 최신 버전에서는 사용자가 UI에서 데이터베이스라고 부르는 대상을 API에서 data source로 다루는 경우가 있습니다. Hermes와 ntn이 처리하므로 입문자가 ID를 직접 복사할 필요는 없지만, 오류 메시지에 database와 data source가 다르게 표시될 수 있다는 점은 알아두면 좋습니다.

9. ‘생성된 Notion 테스트 페이지 열기’로 실제 페이지 확인하기

최종 검증 결과에 있는 생성된 Notion 테스트 페이지 열기 링크를 누르면 Hermes가 테스트로 만든 실제 Notion 페이지가 열립니다.

페이지에서 제목, 본문, 생성 위치를 확인합니다. 결과 메시지에 “생성 성공”이라고 표시된 것만 보는 것보다 링크로 실제 페이지를 열고, 같은 페이지의 재조회까지 성공했는지 확인해야 연결 검증이 끝납니다.

이번 테스트 페이지는 삭제하거나 보관 처리하지 않고 그대로 남겼습니다. 운영 환경에서는 회사 정책에 따라 테스트 페이지를 보관하거나, 삭제 전에 다시 승인을 받아 정리하세요.

검색 결과가 비어 있으면 토큰부터 다시 만들기보다 Integration의 Content access, 대상 워크스페이스, 페이지 위치, Gateway의 환경변수 재로딩 여부를 먼저 확인합니다.

10. Gateway 재시작

마지막으로 실행 중인 Gateway가 새 Notion 환경변수를 기본으로 읽도록 재시작합니다. 이번 실제 검증처럼 Slack 스레드에서 Gateway 명령을 사용할 수 있다면 같은 스레드에 다음 명령을 보냅니다.

!restart

SSH 터미널에서 직접 관리할 때는 Hermes CLI의 Gateway 명령을 사용합니다.

hermes gateway restart
hermes gateway status

두 방법을 연달아 실행할 필요는 없습니다. 자신이 Gateway를 관리하는 경로 하나를 사용한 뒤 새 세션에서 읽기 요청을 다시 시험합니다.

Notion에서 연결된 업무 페이지를 찾아 제목과 마지막 수정일만 보여줘.
페이지를 수정하거나 새로 만들지는 마.

환경 파일을 수정하기 전에 시작된 기존 Gateway 프로세스는 새 값을 모를 수 있습니다. 토큰 등록 직후의 일회성 CLI 검증이 성공했더라도, Discord나 Slack에서 계속 사용하려면 Gateway 재시작과 새 세션 확인까지 마치세요.

연결이 안 될 때 확인 순서

회사 워크스페이스가 선택 목록에 없음

• 현재 계정이 Workspace Owner인지 확인합니다.
• 일반 멤버라면 Owner에게 Internal Integration 생성을 요청합니다.
• 관리자가 만든 연결이 정확한 회사 워크스페이스에 설치됐는지 확인합니다.

검색 결과가 비어 있거나 페이지가 404로 나옴

• Content access에 페이지 또는 데이터베이스를 추가했는지 확인합니다.
• Notion 페이지의 공유·연결 메뉴에서 해당 Integration이 보이는지 확인합니다.
• 다른 워크스페이스에서 발급한 토큰이 아닌지 확인합니다.

Notion API는 권한이 없는 페이지에 대해 존재 여부를 숨기기 위해 404처럼 응답할 수 있습니다. 브라우저에서 페이지가 보인다는 사실만으로 Integration도 볼 수 있는 것은 아닙니다.

인증 오류가 남

• NOTION_API_KEY와 NOTION_API_TOKEN에 같은 실제 토큰을 넣었는지 확인합니다.
• 값 앞뒤에 공백이나 따옴표가 잘못 들어가지 않았는지 확인합니다.
• 토큰이 재발급된 뒤 예전 값이 남아 있지 않은지 확인합니다.
• secret을 화면에 출력하지 말고 Hermes에게 길이·접두사 인식과 실제 인증 요청 결과만 확인하도록 합니다.

읽기는 되지만 페이지 생성이 실패함

• 콘텐츠 삽입 권한이 활성화됐는지 확인합니다.
• 생성할 부모 페이지가 Content access 범위에 포함됐는지 확인합니다.
• 회사 정책에서 연결의 쓰기 권한을 제한하지 않았는지 관리자에게 확인합니다.
• 처음부터 기존 페이지 수정이나 데이터베이스 대량 입력을 시도하지 말고 테스트 페이지 하나로 범위를 좁힙니다.

운영 전 보안 체크리스트

연결 후 바로 써볼 안전한 요청 예시

처음에는 읽기 작업만 요청합니다.

Notion에서 이번 주 회의 페이지를 찾아줘.
제목, 작성일, 핵심 결정사항만 요약하고 페이지는 수정하지 마.

데이터베이스도 조회부터 시작합니다.

연결된 업무 데이터베이스에서 상태가 진행 중인 항목을 최대 10개 조회해줘.
이름, 담당자, 마감일만 표로 보여주고 속성은 변경하지 마.

새 페이지가 필요하면 초안을 먼저 받습니다.

오늘 회의 내용을 Notion 회의록 페이지로 만들 초안을 작성해줘.
제목, 본문, 생성할 부모 페이지를 먼저 보여주고
내가 승인하기 전에는 Notion에 쓰지 마.

Notion 연결은 검색과 요약만으로도 충분히 유용합니다. 수정·댓글·페이지 생성·데이터베이스 업데이트는 외부 상태를 바꾸므로 작업 대상을 좁히고 승인 단계를 유지하세요.

공식 자료

• Notion API Quickstart
• Notion API Overview와 내부 연결 접근 방식
• Notion Authorization과 Workspace Owner 요구 사항
• Notion Integrations Developer Portal
• Hermes Agent Notion bundled Skill 공식 문서
• Hermes Agent 환경변수 공식 문서

정리

이번 6편에서는 회사 Notion 워크스페이스에 Hermes용 Internal Integration을 연결했습니다. Workspace Owner가 아닌 계정에서는 회사 워크스페이스를 선택할 수 없어 관리자에게 생성을 요청했고, 콘텐츠 읽기·업데이트·삽입 권한과 필요한 업무 페이지 접근 범위만 설정했습니다.

발급된 Internal Integration Secret은 Slack이나 Discord로 공유하지 않고 라즈베리파이의 ~/.hermes/.env에 NOTION_API_KEY, NOTION_API_TOKEN, NOTION_KEYRING=0으로 저장했습니다. 파일 권한을 600으로 제한한 뒤 공식 ntn CLI 인증, 페이지 검색, Markdown 읽기, 데이터베이스 조회를 먼저 확인했습니다.

쓰기 테스트는 생성할 제목·본문·부모 페이지를 먼저 검토하고 승인한 뒤 실행했습니다. 테스트 페이지 생성과 재조회까지 성공했고, 마지막으로 Gateway를 재시작해 새 Notion 환경변수를 상시 세션에 반영했습니다.

이제 라즈베리파이5의 Hermes는 허용된 Notion 범위 안에서 업무 페이지 검색·요약, 데이터베이스 조회, 승인된 페이지 생성 작업을 수행할 수 있습니다. 운영 원칙은 Google Workspace 연결과 같습니다. 읽기부터 검증하고, 쓰기는 초안을 확인한 뒤 승인해서 실행합니다.