첫 주에는 개인 웹 화면에서 시험한다면 내장 자격 증명 저장을 선택하고, 파이썬 에스디케이·씨아이·재현 가능한 작업이라면 실행 시점에 환경 변수를 주입하면 됩니다. 여러 사람이 쓰는 원격 맥은 하나의 키를 함께 쓰지 말고, 제한된 실행 계정과 교체 책임자를 먼저 정해야 합니다. 딥시크 하니스 API 키 저장에서 중요한 기준은 어느 화면이 편한지가 아니라 누가 소유하고, 누가 읽으며, 누가 교체하는가입니다.
이 글은 개인 맥에서 처음 모델을 설정하는 개발자, 공유 또는 원격 맥을 운영하는 플랫폼 담당자, 퇴사자 회수와 키 교체 규칙을 정해야 하는 팀 책임자를 위한 글입니다.
SECTION 01 첫 주의 판단 기준
처음 구성할 때는 저장 위치보다 실행 주체를 먼저 적어야 합니다. 아래 세 문장을 채우지 못하면 키를 저장하기 전에 접근 구조부터 다시 설계해야 합니다.
- 키의 소유자는 개인인가요, 팀인가요, 특정 작업 계정인가요?
- 실제 키를 읽을 수 있는 계정은 누구인가요?
- 키가 폐기되었을 때 어떤 작업을 멈추고, 누가 새 키를 넣나요?
공식 동작 기준으로 웹 화면에서 저장한 자격 증명은 화면에 전체 값이 다시 표시되지 않습니다. 설정 파일에는 자격 증명에 대한 참조가 남고, 화면에는 탈취에 바로 사용할 수 없는 설명만 반환됩니다. 기본 저장 위치와 설정 동작은 공식 제공자 설정 안내와 공식 모델 설정 안내에서 버전별로 다시 확인해야 합니다.
다만 파일이 화면에 보이지 않는다는 이유만으로 비밀 값이 보호된다고 판단하면 안 됩니다. 같은 맥의 관리자 계정, 백업 프로그램, 원격 접속 사용자, 작업 프로세스가 해당 파일이나 참조된 값을 읽을 수 있는지가 실제 보안 경계입니다.
SECTION 02 저장 위치별 책임
| 방식 | 적합한 사용자 | 장점 | 먼저 확인할 위험 |
|---|---|---|---|
| 웹 화면 내장 저장 | 개인 맥에서 대화형으로 시험하는 사용자 | 설정이 빠르고 화면에 실제 키가 반복 표시되지 않음 | 로컬 계정, 백업 범위, 원격 접속 권한 |
credentials.yaml |
단일 사용자 중심의 지속 설정 | 설정 파일과 실행 환경을 함께 복원하기 쉬움 | 파일 권한과 실행 계정이 넓으면 읽기 범위도 넓어짐 |
| 환경 변수 | 파이썬 에스디케이, 씨아이, 예약 작업 | 코드를 수정하지 않고 실행마다 교체 가능 | 시작 로그, 프로세스 정보, 배포 설정에 값이 노출될 수 있음 |
| 팀별 자격 증명 관리 | 공유 맥과 다수 작업 | 소유권과 교체 이력을 분리하기 쉬움 | 하니스에 기본 통합 기능이 있다고 가정하면 안 됨 |
개인 웹 화면 사용자는 내장 저장을 사용해도 됩니다. 단, 개인 계정으로 로그인하고, 다른 사용자가 같은 홈 디렉터리를 읽지 못하게 하며, 설정 파일을 무심코 공유 백업에 넣지 않아야 합니다. 개인 시험과 팀 운영은 같은 저장 방식을 쓰더라도 책임 범위가 다릅니다.
credentials.yaml을 별도 관리하는 경우에는 파일의 존재 여부보다 권한을 확인해야 합니다. 일반 사용자가 읽을 수 있는지, 원격 세션에서 파일 경로가 노출되는지, 진단 명령이 파일 내용을 출력하는지 순서대로 점검하십시오.
SECTION 03 파이썬과 자동화 작업
파이썬 에스디케이는 실행 시점 환경 변수와 잘 맞습니다. 공식 예시는 DEEPSEEK_API_KEY를 사용하며, 호출 코드에 실제 키를 직접 넣지 않는 구조를 보여 줍니다. 파이썬 호출 예시와 인증 헤더 예시를 기준으로 환경 변수 이름과 인증 방식을 확인할 수 있습니다. 키를 발급하고 인증 헤더에 넣는 기본 원칙은 딥시크 공식 인증 안내에서도 확인할 수 있습니다.
export DEEPSEEK_API_KEY="실제 값은 여기에 기록하지 마십시오"
python run_agent.py
이 명령 자체를 저장소에 넣어서는 안 됩니다. 다음 파일도 같은 이유로 점검 대상입니다.
- 셸 시작 파일에 실제 키를 고정한 설정
- 키가 포함된 실행 스크립트
- 테스트 로그와 오류 출력
- 작업 정의 파일과 배포용 압축 파일
- 화면 녹화나 터미널 복사 기록
환경 변수는 코드 변경 없이 키를 바꾸기 쉽다는 장점이 있지만, 모든 노출을 자동으로 막아 주지는 않습니다. 프로세스 목록, 디버그 로그, 실패한 작업의 환경 출력에 값이 들어가는지 확인해야 합니다. 씨아이 또는 원격 지속 작업에서는 개인 계정이 아니라 작업 계정에만 변수를 주입하고, 작업이 끝난 뒤 환경을 폐기하는 흐름이 적합합니다.
자동화 작업의 인증은 특정 맥에 묶지 말고 실행 정체성에 묶어야 합니다. 예를 들어 고객 프로젝트 작업, 내부 분석 작업, 비용 센터가 다른 배치 작업이 같은 키를 기본으로 사용하면 사용량 추적과 책임 구분이 어려워집니다. 딥시크 공식 API 문서에서 사용하는 요청 방식이 바뀌었는지도 배포 전에 확인하십시오.
SECTION 04 사람별 선택 조건
다음 조건으로 결정하면 됩니다.
- 개인 맥에서 며칠간 대화형으로 시험하고, 접근 사용자가 본인 한 명이면 내장 웹 화면 저장을 선택합니다.
- 파이썬 에스디케이를 실행하거나 작업 디렉터리를 새로 만들 일이 많으면 환경 변수로 전환합니다.
- 씨아이, 예약 실행, 원격 지속 작업이면 작업 계정에만 키를 주입하고 로그에서 비밀 값이 제거되는지 검증합니다.
- 여러 사람이 같은 맥을 사용하면 관리자, 작업 실행 계정, 일반 접근 계정을 분리합니다.
- 고객별 또는 프로젝트별 비용과 책임을 구분해야 하면 키도 분리합니다.
- 키 교체 때 모든 작업을 동시에 멈출 수 없다면 공용 키 하나를 쓰지 말고 작업 단위로 나눕니다.
- 파일 권한과 원격 접속 범위를 통제할 수 없다면 로컬 파일 저장을 계속하지 말고 실행 계정 격리부터 해결합니다.
팀 공유 환경에서 가장 흔한 실패는 관리자 편의를 위해 모든 사용자가 같은 홈 디렉터리와 같은 키를 사용하는 것입니다. 이 방식은 초기 설정은 빠르지만, 사용 기록이 섞이고 한 번의 폐기 작업이 모든 작업을 끊습니다. 원격 맥 계정과 권한을 정리하려면 원격 맥 접근 권한 안내를 함께 확인하십시오.
SECTION 05 교체와 폐기 시점
키 관리는 생성, 전달, 사용, 교체, 폐기의 다섯 단계로 기록하는 편이 좋습니다.
| 단계 | 담당자 | 남겨야 할 증거 | 실패 시 조치 |
|---|---|---|---|
| 생성 | 키 소유자 | 생성 시점과 적용 범위 | 범위가 불명확하면 사용 중지 |
| 전달 | 관리자 또는 보안 담당자 | 전달 대상과 전달 방식 | 채팅·문서에 남았으면 즉시 교체 |
| 사용 | 작업 계정 담당자 | 실행 계정과 프로젝트 연결 | 로그에 값이 보이면 작업 중단 |
| 교체 | 서비스 또는 프로젝트 담당자 | 새 값 적용 확인 | 새 요청과 기존 세션을 따로 시험 |
| 폐기 | 키 소유자 | 폐기 시점과 중지된 작업 | 관련 작업의 재시작을 차단 |
API 키를 바꾸면 새로 시작하는 요청은 새 인증 정보를 사용합니다. 그러나 실행 중인 프로세스가 시작할 때 읽은 환경을 계속 보유하는지, 세션이 자격 증명 참조를 다시 읽는지는 구성과 버전에 따라 확인해야 합니다. 그러므로 교체 직후에는 새 요청 성공 여부, 기존 세션의 다음 요청, 실패 시 오류 메시지를 각각 확인하십시오.
제공자를 바꾸거나 자격 증명을 삭제하면 새 요청이 실패할 수 있습니다. 반면 이전 세션 기록에는 모델과 제공자 식별 정보가 남을 수 있으므로, 기록에 실제 비밀 값이 들어갔는지도 별도로 검사해야 합니다. 자동 교체, 운영체제 키체인, 기업용 비밀 관리 시스템이 딥시크 하니스에 기본 내장되어 있다고 전제해서는 안 됩니다.
주의: 탈출된 파일이 없다는 것과 키를 읽을 수 없다는 것은 같은 뜻이 아닙니다. 실행 계정, 관리자 권한, 백업 범위, 원격 접속 권한을 모두 확인해야 합니다.
SECTION 06 자주 묻는 내용
저장된 키의 위치
웹 화면에 저장한 키는 화면에서 전체 값을 다시 보는 방식이 아닙니다. 공식 설정 기준의 기본 경로는 $DSH_HOME/.credentials.yaml이며, 설정에는 실제 값 대신 참조가 남을 수 있습니다. 따라서 파일을 찾을 때는 현재 실행 계정의 DSH_HOME 값과 버전을 함께 확인해야 합니다.
파이썬 에스디케이의 읽기 방식
파이썬 에스디케이는 DEEPSEEK_API_KEY 환경 변수를 실행 전에 주입하는 방식이 적합합니다. 코드 내부의 문자열, 프로젝트 설정 파일, 문서 예시에는 실제 값을 넣지 마십시오. 환경 변수가 비어 있을 때 작업이 즉시 실패하도록 시작 단계에서 검사를 넣으면 잘못된 계정으로 요청하는 사고를 줄일 수 있습니다.
원격 맥의 공용 키
원격 맥에서 여러 사람이 한 키를 공유하는 방식은 임시 시험에는 가능하지만, 팀 운영의 기본값으로 삼기 어렵습니다. 사용자를 구분할 수 없고, 한 프로젝트의 폐기 작업이 다른 프로젝트까지 중단되기 때문입니다. 작업 계정과 프로젝트별 키를 분리할 수 있을 때만 제한적으로 사용하십시오.
이전 세션의 지속 여부
키 교체 뒤 이전 세션이 계속되는지는 세션과 실행 프로세스가 인증 정보를 읽는 시점에 달려 있습니다. 새 요청 성공만 확인하고 끝내지 말고, 기존 세션의 후속 요청도 시험하십시오. 폐기된 키를 사용하는 작업이 남아 있으면 성공 여부와 관계없이 중지 신호를 정의해야 합니다.
SECTION 07 이번 주에 할 일
이번 주에는 먼저 계정 목록과 작업 목록을 한 장에 적고, 각 항목에 키 소유자와 교체 담당자를 배정하십시오. 개인 웹 화면 시험은 내장 저장으로 시작해도 되지만, 파이썬 에스디케이와 씨아이로 넘어가는 시점에는 환경 변수 주입으로 바꾸는 것이 좋습니다. 공유 맥에서 계정 구분이 되지 않는다면 키를 복사하기보다 먼저 권한 격리를 완료해야 합니다.
현재 장비에서 모든 사용자가 같은 맥 계정과 같은 설정 파일을 쓰고 있다면 책임 추적이 어렵고, 키 교체 때 전체 작업이 동시에 중단되며, 원격 접속과 백업 경로가 예상보다 넓어지는 문제가 생깁니다. 이런 조건에서는 장비를 더 추가하는 것보다 계정과 실행 환경을 나누는 편이 먼저입니다. 단기간에 격리된 맥 작업 환경이 필요하다면 VPSNIX의 맥 환경 안내를 확인하고, 사용 전에 소유권과 교체 절차가 정리되는지부터 점검하십시오.
마지막으로 개인 시험인지, 자동화 작업인지, 팀 공유인지에 따라 저장 방식을 선택하고, 실제 키가 없는 교체 점검표를 따로 보관하십시오. 키의 소유자와 실행 계정을 정할 수 없는 공유 환경이라면 Agent를 시작하기보다 격리 구조를 먼저 완성하는 것이 안전합니다.
SECTION 08 자주 묻는 질문 FAQ
딥시크 하니스에 저장한 API 키는 어디에서 확인하나요?
웹 화면에서 저장한 뒤에는 실제 키 전체가 다시 표시되지 않고, 설정 파일에는 자격 증명 참조가 남는 방식으로 확인합니다. 공식 동작 기준으로 저장 위치는 DSH_HOME 아래의 .credentials.yaml입니다. 따라서 파일이 보이지 않는다고 키를 읽을 수 없는 것은 아니며, 파일 권한과 실행 계정의 접근 범위를 함께 점검해야 합니다.
Python SDK는 딥시크 API 키를 어떻게 읽어야 하나요?
Python SDK와 독립 실행 작업에서는 DEEPSEEK_API_KEY 환경 변수를 실행 시점에 주입하는 방식이 우선입니다. 코드에 키를 넣지 않고 프로젝트별 실행 계정이나 작업 설정에서 값을 바꿀 수 있기 때문입니다. export 명령, 실제 키가 들어간 환경 설정 파일, 비밀 값이 포함된 시작 스크립트는 저장소에 커밋하지 않아야 합니다.
원격 Mac에서 여러 사람이 하나의 모델 키를 같이 써도 되나요?
기술적으로는 가능할 수 있지만 팀 운영 기준으로는 기본 선택이 아닙니다. 하나의 키를 공유하면 누가 사용했는지 추적하기 어렵고, 교체할 때 모든 작업이 동시에 중단될 수 있습니다. 관리자, 작업 실행 계정, 일반 사용자를 분리하고 고객 프로젝트와 내부 프로젝트의 키도 가능한 한 나누는 편이 안전합니다.
API 키를 바꾸면 기존 세션도 계속 실행되나요?
새 키로 교체하면 이후에 시작하는 요청은 새 인증 정보를 사용하게 됩니다. 다만 기존 세션이 즉시 종료되거나 계속된다고 단정해서는 안 됩니다. 세션이 저장한 인증 참조 방식과 실행 프로세스의 환경을 확인하고, 교체 직후 새 요청과 기존 세션을 각각 시험해야 합니다. 과거 기록에 남은 모델과 제공자 표시는 별도로 검토해야 합니다.