문서 / API와 에이전트
Claude, Codex, MCP: 에이전트 도구
Phosphene은 로컬 서버(스튜디오) 하나이고, 브라우저 페이지, Mac 앱, 에이전트 도구가 모두 같은 HTTP API(API.md)로 이 서버와 통신해요. 그 위에 작은 도구 두 가지가 agents/에 있어요.
| 설명 | 실행 방법 | |
|---|---|---|
agents/phosphene_cli.py | phosphene 명령어: 영상, 이미지, 음성, 음악 만들기, 작업 목록 보기, 대기, 파일 가져오기, 상태 확인 | 아무 python3(3.9 이상, 표준 라이브러리만 사용) |
agents/phosphene_mcp.py | 같은 동작을 제공하는 MCP 서버(stdio). Claude Code, Codex 등 모든 MCP 클라이언트용 | 위와 같음 |
둘 다 agents/phosphene_client.py 위에 얹은 얇은 계층이라서 스튜디오를 찾는 방식이 같고, 스튜디오가 실행 중이 아닐 때 보여 주는 메시지도 같아요.
에이전트 연결하기
Mac 앱(5.0.9 이상): Phosphene을 열고 도움말 → 에이전트 연결을 고르세요. Claude Code, Codex, 데스크톱 클라이언트 중 하나를 선택해서 명령어나 설정을 복사하세요. 앱이 Pro를 포함해 내 설치에 맞는 정확한 경로를 채워 줘요. 에이전트가 작업하는 동안에는 Phosphene을 켜 두세요. 이후 업데이트로 경로가 바뀌면 같은 메뉴에서 새 연결 정보를 복사하세요.
Pinokio: Phosphene을 시작한 다음 Pinokio가 보여 주는 스튜디오 주소 뒤에 /agents/info를 붙여 열어 보세요. 기본 설치라면 http://127.0.0.1:8198/agents/info예요. agents 섹션에 명령어와 설정이 들어 있어요. 이 주소는 Pinokio용이고, Mac 앱은 대신 도움말 메뉴를 써요.
MCP 도구: phosphene_status, phosphene_make_video, phosphene_make_image, phosphene_make_speech,
phosphene_make_music, phosphene_list_jobs, phosphene_wait, phosphene_fetch, phosphene_stop.
렌더링은 몇 분 걸려요. make_* 도구는 작업을 대기열에 넣고 작업 id를 바로 돌려줘요. phosphene_wait는 최대
timeout_sec(기본 1500초) 동안 기다리며, 다시 호출할 수 있어요.
CLI
phosphene status
phosphene video "A night ferry crosses a dark harbour in light rain ..." --seconds 5 --out ./clips
phosphene video "..." --engine h3 --quality draft --seconds 10 --wait
phosphene video "..." --image still.png # image to video (the picture is uploaded first)
phosphene image "a travel poster of a red tram" --n 2 --aspect 3:4 --out ./stills
phosphene jobs ; phosphene wait JOB --out DIR ; phosphene fetch JOB --out DIR ; phosphene stop
phosphene servers # every studio answering on this Mac
어떤 명령어든 --json을 붙이면 기계가 읽을 수 있는 출력이 나와요. 종료 코드: 0은 성공, 1은 스튜디오가 거부했거나 작업이 실패한 경우(그 이유 문장이 출력돼요), 2는 잘못된 인수, 3은 Phosphene이 실행 중이 아닌 경우예요.
(여기서 phosphene은 python3 agents/phosphene_cli.py를 뜻해요. 원하는 대로 별칭을 만드세요.)
도구가 스튜디오를 찾는 방법
스튜디오의 포트는 실행 위치에 따라 달라요. Pinokio는 8198, 개발 프로필은 8199, Mac 앱은 8930-8999 범위의 빈 포트(PanelProcess.freePort)이고, LTX_PORT로 아무 값이나 지정할 수도 있어요. 그래서 이런 순서로 찾아요.
PHOSPHENE_URL이 설정되어 있으면 그것만 써요.- 모든 스튜디오는 리스너가 연결된 직후
~/.phosphene/servers/<port>.json을 쓰고, 종료할 때 지워요(agent_discovery.py). 기록은 pid가 살아 있고 그 URL이GET /agents/info에"app": "phosphene"으로 응답할 때만 신뢰해요. 최신 기록부터 확인해요.PHOSPHENE_DISCOVERY_DIR로 폴더를 옮기고,PHOSPHENE_DISCOVERY=0으로 알림을 끌 수 있어요. - 기록이 없으면(이전 버전 스튜디오) 8198, 8199, 그다음 8930-8999를 차례로 확인해요.
응답하는 곳이 없으면 이런 메시지가 나와요. “Phosphene is not running on this Mac. Start it first: open the Phosphene app, or press Start on Phosphene in Pinokio.” (CLI는 종료 코드 3, MCP 도구는 충돌이 아니라 도구 오류예요.)
Free, Pro, 라이선스
이 도구들은 경로를 추가하지 않고 아무것도 대신 결정하지 않아요. 모든 요청은 페이지가 직접 보내는 요청(/queue/add, /speech/generate, /upload, /status, /file)과 같아서, 스튜디오가 똑같은 검사를 적용해요. 이 Mac에서 무엇을 실행할 수 있는지, 모델 라이선스(사용자가 동의하기 전까지 HTTP 451), Free와 Pro에 무엇이 들어 있는지를 확인해요. 폼은 Pro 속도 프로필을 작업에 실어 보낼 수 없어요(make_job은 허용 목록으로 params를 만들고, test_agent_tools.py가 이를 고정해요). 모델 라이선스에 동의하는 도구는 일부러 만들지 않았어요. 누군가를 대신해 동의하는 것은 그 사람의 동의를 대신하는 일이므로, 사용자가 Phosphene에서 직접 한 번 동의해야 해요.
GET /agents/info
{"app": "phosphene", "api": 1, "url": "http://127.0.0.1:8198", "port": 8198, "pid": 123,
"version": "5.0.0", "distribution": "pinokio" | "mac-app", "edition": "free" | "pro", "profile": "production",
"pro": {"active": false, ...}, // GET /pro/status
"engines": {"ltx": {"available": true, "qualities": [...]},
"h3": {"available": false, "qualities": [...], "lengths": ["3s", "5s", "10s", "15s", ...]},
"speech": {...}, "music": {...}, "image": {...}},
"outputs_dir": "...",
"agents": {"cli": "...", "mcp": "...", "python": "...", "mcp_config": {...}, "claude_code": "...", "codex": "..."}}
가볍고(디스크를 훑지 않아요) 반복해서 호출해도 안전해요. 테스트: test_agent_tools.py.
출처: docs/AGENT_TOOLS.md (공개 저장소). 공개 전에 이 웹사이트용으로 검토했어요. 영어 원문에서 번역했어요. 수정 제안하기.