VoiceOS Instagram 통합

Mac 노치에서 음성으로 Instagram 계정을 운영하세요. 계정 상태를 묻고, 댓글과 DM을 읽고, 노치에 사진을 드롭하고 캡션을 말하면 사진이나 캐러셀을 게시할 수 있습니다.

비즈니스 또는 크리에이터 계정이 필요합니다. Instagram API는 개인 계정에서 인사이트, 댓글, DM, 게시 기능을 제공하지 않습니다. 이는 우리가 아니라 Meta의 규칙이며, 우회할 방법이 없습니다.

전환 방법: Instagram 앱 → 내 프로필 → ☰ 메뉴 → 설정 및 개인정보 → 계정 유형 및 도구 → 전문 계정으로 전환. 크리에이터 또는 비즈니스를 선택한 후 안내를 따르세요. 무료이고, 되돌릴 수 있으며, 비공개 계정이었다면 공개로 바뀌지 않습니다. 이후 이 통합을 다시 연결하세요.

설정

여섯 단계입니다. 3단계와 4단계는 게시를 원할 때만 필요합니다. 읽기는 이 단계 없이도 작동합니다.

1. 의존성 설치

cd instagram
bun install

2. Composio를 통해 Instagram 연결

Composio는 이 통합이 사용하는 인증 및 API 전송 계층입니다.

1. Composio 대시보드에서 API 키를 받으세요.

2. Composio 프로젝트에 Instagram을 앱으로 추가하세요. 그러면 연결 흐름에 필요한 인증 구성이 생성됩니다.

실제 Instagram OAuth 승인은 6단계에서 합니다. 여기서는 아직 할 일이 없습니다.

3. 사진 중계 버킷 만들기 (Cloudflare R2)

Instagram은 이미지 바이트를 직접 받지 않습니다. Meta는 자체 크롤러로 공개 URL을 대신 가져옵니다. 따라서 노치에 드롭한 사진은 사용자 자신의 R2 버킷에 업로드되고, 링크로 Instagram에 전달된 후 몇 초 뒤 삭제됩니다.

Cloudflare 대시보드 → R2에서:

1. 버킷을 생성합니다.

2. 버킷을 열고 → 설정 → 공개 개발 URL → 사용을 선택합니다. 해당 URL을 복사하세요. 버킷이 공개여야 하며, 그렇지 않으면 Meta가 사진을 가져올 수 없습니다.

3. API 토큰 관리 → API 토큰 생성에서 해당 버킷 하나로 범위를 한정하고 객체 읽기 및 쓰기 권한을 부여하세요. 비밀 키는 한 번만 표시되므로 지금 복사하세요.

4. 선택 사항이지만 권장: 1일 후 객체를 삭제하는 수명 주기 규칙을 추가하세요. 통합이 각 사진을 직접 삭제하며, 이 규칙은 드물게 누락되는 경우를 위한 안전장치입니다.

읽기만 원한다면 이 단계 전체를 건너뛰세요. account_pulse, post_insights, activity, dm_thread는 버킷 없이도 모두 작동합니다. 버킷이 필요한 것은 create_post와 schedule_post뿐입니다.

4. 서버에 키 제공

이 폴더에 .env 파일을 만드세요:

COMPOSIO_API_KEY=

# Cloudflare R2 — publishing only, leave blank if you are read-only
R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET=
R2_PUBLIC_URL=

R2_ACCOUNT_ID는 Cloudflare R2 → 개요 페이지 오른쪽 상단에 있습니다. R2_PUBLIC_URL은 3단계의 공개 개발 URL입니다.

VoiceOS가 설정 필드로 이 값을 요청하면 그 입력이 우선하며, 이 파일은 서버를 단독 실행할 때만 대체 수단으로 사용됩니다.

5. VoiceOS에 설치

먼저 VoiceOS를 종료하세요. VoiceOS는 config.json을 메모리에 보관했다가 종료 시 다시 작성하므로, 실행 중에 기록된 내용은 오류 없이 조용히 사라집니다. 설치 프로그램은 VoiceOS가 실행 중이면 실행을 거부합니다.

osascript -e 'quit app "VoiceOS"'
python3 install-into-voiceos.py
open -a VoiceOS

이 명령은 이 폴더를 ~/Library/Application Support/VoiceOS/custom-mcps/로 복사하고, 4단계의 키를 함께 옮기며, 등록합니다. 단순한 cp로는 충분하지 않습니다. VoiceOS는 config.json에 두 개의 항목(하나는 서버 실행 방법, 다른 하나는 매니페스트)도 필요로 하며, 이를 작성하는 것이 스크립트가 하는 일의 대부분입니다. 스크립트는 먼저 config.json을 백업합니다.

--update는 매번 매니페스트에서 confirmTools를 다시 도출합니다. 이는 보기보다 중요합니다. VoiceOS가 어떤 도구에 확인 카드가 필요한지 결정하는 데 사용하는 목록이며, 이름 변경 후 남은 오래된 항목이 있으면 게시물이 카드 없이 게시될 수 있습니다.

6. 계정 연결

*"내 Instagram 상태가 어때?"*라고 말하세요. Instagram이 아직 연결되지 않았다면 OAuth 링크가 있는 Instagram 연결 카드가 표시됩니다. 한 번 승인하면 끝입니다.

계정이 개인 계정이라고 표시되면 이 페이지 상단의 안내 상자로 돌아가세요.

도구

사진을 노치에 드롭하고 같은 호흡으로 말하세요 — "이 두 장을 해커톤에 대한 캡션과 함께 올려줘". 두 게시 도구 모두 실제로 게시되기 전에 카드에 사진, 캡션, 그리고 (예약의 경우) 정확한 시간을 표시합니다.

사진 처리 방식

한 번 읽어볼 가치가 있습니다. 한 단계가 사람들을 놀라게 하거든요.

1. 사진은 Mac에서 sips(macOS에 내장)로 JPEG로 변환됩니다. Instagram은 다른 형식은 받지 않습니다.

2. 사진은 무작위로 추측할 수 없는 이름으로 사용자 자신의 R2 버킷에 업로드되며 몇 초 동안 공개적으로 읽을 수 있습니다. 이는 피할 수 없습니다. Meta의 크롤러는 익명이고 로그인할 수 없으므로, 공개 URL이 Instagram이 사진을 받아들이는 유일한 방법입니다.

3. Instagram이 사진을 가져와 게시물을 게시합니다.

4. 파일은 성공 시 그리고 실패 시에도 finally 블록에서 버킷에서 삭제됩니다. 3단계의 수명 주기 규칙이 안전장치입니다.

버킷은 사용자 소유입니다. 다른 사람의 서버에는 아무것도 저장되지 않으며, 이 통합은 사용자의 사진을 복사본으로 보관하지 않습니다.

예약 게시물은 Instagram 서버가 아니라 사용자 Mac에서 실행됩니다. Instagram에는 예약 API가 없습니다. macOS launchd 타이머가 지정한 분에 깨어나 그때 게시합니다. 따라서 Mac이 켜져 있고 깨어 있어야 합니다. 게시 예정 시간에 Mac이 꺼져 있었다면 게시물은 몇 시간 늦게 게시되는 대신 누락으로 기록되며, 다음에 물어볼 때 instagram_activity가 알려줍니다.

v1에 없는 기능

의도적으로 제외했습니다. 시도하기 전에 알아두세요:

• DM 보내기. Meta는 Composio의 공유 Instagram 앱을 통한 API DM 전송을 차단합니다. 24시간 창이 확실히 열려 있어도 "허용된 창 밖" 오류를 반환합니다. 이 통합은 DM을 읽을 수 있지만 보낼 수는 없습니다. Instagram 앱에서 답장하세요.

• 댓글에 답글 달기. 동일한 전송 제한입니다.

• 비디오 및 Reels. 사진과 사진 캐러셀만 가능합니다. 비디오 게시에는 이 빌드에 없는 재개 가능한 업로드 경로가 필요합니다.

• Stories. 툴킷에서 노출되지 않습니다.

• 24시간 이후로 예약하기. 이 상한은 의도적입니다. 시간이 한 시간 더 늘어날 때마다 지연된 작업이 아무도 볼 수 없는 곳에서 썩어가는 또 다른 경로가 생깁니다. 사진이 삭제되거나, 키가 교체되거나, 연결이 해지될 수 있습니다.

• 다른 계정 읽기. 연결된 계정만 가능합니다.

문제 해결

개발

bun install
bun test          # 224 unit and failure-injection tests
bunx tsc --noEmit -p tsconfig.json

테스트가 보호하기 위해 존재하는 세 가지 규칙입니다. 편집하기 전에 알아두세요:

• stdout은 MCP 통신선입니다. 배포된 코드에 console.log 하나만 있어도 VoiceOS가 JSON-RPC 스트림을 파싱할 수 없게 되어, 앱을 다시 시작할 때까지 통합이 라우팅에서 조용히 사라집니다. 모든 로그는 console.error를 통해 출력됩니다. stdoutGuard.ts는 server.ts의 첫 번째 import이며, 그렇게 하지 않는 의존성을 위해 console을 다시 바인딩합니다.

• 파일 경로로 셸 문자열을 절대 만들지 마세요. 사진은 사용자가 파일을 노치에 드래그하여 제공합니다. execFile(cmd, [args])만 사용하세요. holiday.png; rm -rf ~라는 파일 이름은 sips에게 하나의 불투명한 인자이며, test/media-paths.test.ts가 이를 검증합니다.

• 도구 이름과 설명은 매니페스트와 정확히 일치해야 합니다, 양방향 모두에서요. server.ts와 voiceos.integration.json은 하나의 계약에 대한 두 개의 사본입니다.

confirmations/post_composer.html은 게시 전 카드의 진실의 원천입니다. 매니페스트는 이 파일의 사본을 문자열로 담고 있습니다. HTML을 편집하면 사본도 다시 생성해야 합니다. 그렇지 않으면 되돌릴 수 없는 게시 전에 표시되는 카드가 오래된 것이 됩니다.