Connectors: 앱 계정 연결

기준일: 2026-11-04
문서 반영 버전: v0.22.6
난이도: 중급
공식 기준: Tool Search → Connectors, Tool Gateway → Multiple connector accounts, CLI Commands → hermes connectors, v0.22.0 릴리스 노트

공식 문서에는 Connectors만 다루는 페이지가 아직 없습니다. 이 글은 위 세 문서의 해당 절과 v0.22.0 릴리스 노트를 합쳐 정리했습니다.

개요

Connectors는 v0.22.0에서 들어온 기능으로, 에이전트가 호스팅된 앱 안에서 직접 일하게 해 줍니다. 릴리스 노트는 Linear와 Notion을, 공식 문서는 Gmail을 예로 듭니다. 앱을 요청하면 브라우저에서 한 번 로그인하고, 같은 차례 안에서 그 앱의 도구를 바로 씁니다.

동작 방식은 MCP와 다릅니다. 앱 도구가 로컬에 등록되지 않고 Nous tool gateway(관리형 도구 게이트웨이)가 원격으로 제공합니다. 에이전트가 tool_search로 도구를 찾으면 게이트웨이 결과가 로컬 도구와 함께 검색되고, 이름은 connectors__<connector>__<tool> 형식으로 붙습니다.

어떤 앱이 지원되는지는 문서에 고정 목록이 없습니다. Desktop Connectors 페이지나 hermes connectors list로 그때그때 확인하세요.

언제 쓰나

상황	고를 것
Linear 이슈 만들기, Notion 페이지 정리처럼 SaaS 앱 작업을 시키고 싶다	Connectors
사내 서버, 로컬 DB, 직접 띄운 도구를 붙이고 싶다	MCP
앱 계정 OAuth 처리와 토큰 보관을 직접 하기 싫다	Connectors
데이터가 제3자 게이트웨이를 거치면 안 된다	MCP(로컬) 또는 Connectors 끄기

Desktop에서는 Connectors 페이지가 예전 MCP 탭을 대신합니다. 호스팅 앱과 MCP 서버가 한 목록에 같이 나옵니다.

설정 순서

1단계: Nous 신원 준비

Connectors는 Nous 신원이 있어야 동작합니다. 경로는 두 가지입니다.

• 에이전트나 Desktop에서 시작할 때: Nous 계정이 없어도 됩니다. 처음 manage_connections 동작을 하거나 Desktop Connectors 페이지에서 앱을 연결하면 무료 Nous 신원이 자동으로 만들어집니다. 이 신원은 모델 provider를 바꾸지 않습니다(Nous 무료 티어를 싣는 빌드가 아니면 connectors와 관리형 도구에만 쓰입니다). Connectors 페이지를 여는 것만으로는 만들어지지 않습니다.
• hermes connectors CLI: CLI 레퍼런스는 "Nous Portal 로그인이 필요하다"고 적고 있습니다. 쓸 수 없는 상태면 CLI 출력은 Connectors are not available.과 함께 hermes auth upgrade로 로그인하라는 안내입니다.

신원 자동 생성을 막으려면 다음을 넣습니다.

nous:
  guest: false

2단계: 앱 연결

가장 쉬운 방법은 그냥 시키는 것입니다. "Linear에 이 버그 이슈로 올려 줘"라고 하면, 아직 연결되지 않은 앱 호출은 CONNECTION_REQUIRED 오류를 받고 에이전트가 manage_connections로 연결을 시작합니다. Desktop에서는 카드가 뜨고 연결이 끝나거나 건너뛸 때까지 기다립니다. 다른 표면에서는 앱마다 연결 링크를 돌려줍니다.

터미널에서 직접 하려면:

hermes connectors list                      # 커넥터 목록과 연결 여부
hermes connectors connect gmail             # 링크를 출력하고 연결될 때까지 기다림
hermes connectors connect gmail --alias work
hermes connectors accounts                  # 연결된 계정 보기

connect는 링크를 찍은 뒤 연결되거나 기한이 지날 때까지 기다립니다. Ctrl-C를 누르면 기다리기만 멈춥니다.

3단계: 같은 앱 계정 여러 개

회사 Gmail과 개인 Gmail처럼 한 앱에 계정을 여러 개 붙일 수 있습니다.

규칙	내용
이름	1~32자, 소문자·숫자·-, 첫 글자는 소문자나 숫자. 이름이 없으면 앱의 계정 라벨이 보인다
기본 계정	없다. 이름 붙은 계정이 여럿이면 어느 계정인지 말해야 한다
이름 짓기	에이전트가 사용자의 말에서 골라 짓고, 애매하면 묻고, 지은 이름을 알려 준다
connector_alias	활성 계정이 2개 이상이면 그 앱의 모든 도구에 이 인자가 붙는다. 모든 계정에 이름이 있으면 필수
재연결	지우지 않는다. 같은 이름으로 새 계정을 만들고, 옛 계정은 retired(비활성)로 남긴다
삭제	사용자만 한다. 에이전트는 계정을 지우지 않는다

hermes connectors rename gmail work --to office
hermes connectors connect gmail --alias work --reconnect   # 고장 난 계정 고치기
hermes connectors disconnect gmail --alias home             # 확인을 묻는다. --yes로 생략
hermes connectors accounts gmail --all                      # retired 계정까지 표시

rename은 Nous Portal 쪽이 지원해야 합니다. 아직 지원하지 않으면 This Nous Portal cannot rename connector accounts yet.이 나옵니다. --reconnect는 이미 정상인 계정에는 아무것도 하지 않고, 다시 로그인하려면 --force를 붙입니다.

계정 관리는 Desktop Connectors 페이지, TUI /connectors, CLI hermes connectors, Nous Portal 어디서나 됩니다.

끄는 법

Connectors 경로를 아예 쓰지 않으려면:

tools:
  connectors:
    enabled: false

이렇게 하면 tool_search가 게이트웨이를 전혀 부르지 않고, 기능이 없는 것처럼 동작합니다. nous.guest: false만 넣은 경우에도 신원이 없으면 connectors 관련 내용은 보이지 않고 모델에게 오류도 나오지 않습니다.

주의할 점

• 데이터 경로: 앱 호출은 Nous tool gateway를 거칩니다. 회사 계정을 붙이기 전에 사내 정책에서 외부 중계가 허용되는지 확인하세요. v0.22.0 릴리스 노트에 따르면 connector 도구는 로컬 파일을 첨부로 보낼 수도 있습니다.
• 게이트웨이 장애: 게이트웨이 호출은 30초로 제한되고, 느리거나 응답이 없으면 로컬 결과만으로 동작합니다.
• 승인: tool_call 묶음 안의 항목마다 승인이 따로 처리되고, 중간에 /stop하면 아직 시작하지 않은 항목은 보내지 않습니다.
• 연결 해제: 모델 도구로는 계정을 끊을 수 없습니다. 사용자가 Portal이나 위 명령으로 직접 합니다.

체크리스트

• Nous 신원이 자동 생성되는 경로와 nous.guest: false 설정을 이해했다
• hermes connectors list로 쓸 수 있는 앱을 확인했다
• 같은 앱 계정이 여럿이면 이름(--alias)을 붙였다
• 회사 계정을 붙이기 전에 외부 게이트웨이 경유가 허용되는지 확인했다

다음 단계

• Nous Tool Gateway: Connectors가 올라타는 게이트웨이
• MCP와 도구: 로컬·사내 도구를 붙이는 다른 방법
• 업무 PC에서 Hermes 안전하게 쓰기