피드로 돌아가기
Dev.toDevOps
원문 읽기
I Tried Four Wrong Ways to Configure a Voyage AI API Key. The Fifth One Worked.
OpenClaw 사용자가 Voyage AI API 키 설정 시 4가지 잘못된 방식을 시도한 후 auth-profiles.json 기반 per-agent 인증 구조 도입으로 서버 재부팅 후에도 의미론적 메모리 검색 기능 정상 작동
AI 요약
Context
OpenClaw AI 에이전트에 Voyage AI 기반 의미론적 메모리 검색을 추가했으나, 서버 재부팅 후 VOYAGE_API_KEY 환경 변수가 지속되지 않아 모든 메모리 검색 요청이 인증 오류로 실패하는 상황이 발생했다.
Technical Solution
- systemd Environment= 설정 대신 auth-profiles.json 기반 per-agent 인증 구조 도입: ~/.openclaw/workspace-/auth-profiles.json 파일에 voyage:default 엔트리 추가
- 1Password 동적 참조 방식 적용: op://openclaw/Voyage/credential 형태의 1Password 링크를 런타임에 해석하여 평문 키 제거
- 각 에이전트별 독립적인 인증 프로필 관리: 13개 모든 에이전트의 auth-profiles.json 파일에 voyage:default 항목 개별 추가
- 기존 환경 변수 및 systemd 설정 제거: .bashrc와 systemd 서비스 파일에 작성된 모든 API 키 관련 설정 정리
- 스키마 검증 기반 설정 관리: OpenClaw 게이트웨이 시작 시 config JSON 스키마 사전 확인으로 부분 수정으로 인한 충돌 방지
Impact
의미론적 쿼리가 minScore 0.22 이상의 관련 결과를 즉시 반환하며, 모든 13개 에이전트가 독립적으로 인증을 해석하고 서버 재부팅 후에도 메모리 검색 기능이 지속적으로 작동함.
Key Takeaway
OpenClaw와 같은 per-agent 아키텍처 시스템에서는 전역 환경 변수나 통합 secrets 파일이 아닌 각 에이전트의 로컬 auth-profiles.json을 인증 출처로 사용하면, 에이전트별 격리된 자격증명 관리와 런타임 동적 해석을 통해 평문 키 노출 없이 재부팅 후에도 지속성을 보장할 수 있다.
실천 포인트
멀티 에이전트 아키텍처를 운영하는 엔지니어가 외부 API 키를 설정할 때, systemd 환경 변수나 전역 config 파일 대신 각 에이전트의 로컬 auth-profiles.json에 1Password 참조(op://vault/item/field 형식)를 저장하면 키 평문 노출을 제거하면서도 서버 재부팅 시에도 인증 정보가 지속되고 에이전트별 다른 키 사용이 가능해진다.