환경 변수 저장과 재시작

AI 앱이 환경 변수(ENV)에서 dtxWiki 액세스 키를 읽는 경우의 안내입니다. 먼저 액세스 키를 만든 뒤, 앱이 실행되는 컴퓨터와 환경에 맞는 절차를 선택하세요. dtxWiki 서버가 다른 컴퓨터에 있어도 이 설정은 AI 앱을 사용하는 컴퓨터에서 진행합니다.

재시작하면 왜 연결이 끊기나요?

환경 변수는 실행 중인 프로그램에 전달하는 이름과 값입니다. 여기서는 이름이 DTXWIKI_MCP_PAT, 값이 비밀 정보인 dtxWiki 액세스 키입니다. OpenAI나 Anthropic의 API 키와는 별개입니다.

터미널의 export DTXWIKI_MCP_PAT=...는 해당 셸과 거기서 실행하는 프로그램에만 값을 전달합니다. 다음 로그인에도 쓰도록 저장하지는 않습니다. 따라서 MCP 등록은 파일에 남아 있어도 터미널을 닫거나 컴퓨터를 재시작하면 키 값이 사라질 수 있습니다.

저장한 항목	재시작 후 상태
터미널의 export 또는 PowerShell의 $env:DTXWIKI_MCP_PAT만 설정	임시 값입니다. 새 세션에서는 다시 준비해야 합니다.
Codex의 bearer_token_env_var = "DTXWIKI_MCP_PAT"	변수 이름은 남습니다. Codex를 실행할 때 실제 값도 필요합니다.
Windows 사용자 환경 변수	다음 세션에서도 사용할 수 있도록 Windows가 값을 보관합니다.
macOS/Linux 키 파일과 셸 시작 설정	새 셸이 저장한 값을 읽습니다. 해당 셸에서 앱을 실행합니다.

조직에서 비밀값 관리 도구를 제공한다면 그 도구가 안내하는 실행 시 변수 전달 방법을 따르세요. 아래 로컬 저장 방식은 Windows 사용자 설정이나 개인 파일에 비밀값을 평문으로 저장합니다. 보호된 개인 계정에서 사용하고 Git, 설정 동기화, 공유 백업, 화면 캡처에 값이 포함되지 않게 하세요.

Windows: 사용자 환경 변수로 저장

Windows에서 직접 실행하는 앱은 이 절차를 따릅니다. VS Code에서 WSL을 사용한다면 WSL 안내를 따르세요.

1. 시작 메뉴에서 계정의 환경 변수 편집을 검색해 엽니다. 시스템 환경 변수 편집을 열었다면 그 창의 환경 변수…를 누릅니다.
2. 위쪽의 내 계정에 대한 사용자 변수 영역에서 새로 만들기…를 누릅니다. 사용자 변수는 관리자 권한 없이 설정할 수 있습니다.
3. 변수 이름에 DTXWIKI_MCP_PAT를 입력합니다. 변수 값에는 dtxWiki에서 복사한 액세스 키만 붙여넣습니다. 따옴표, Bearer, export는 넣지 마세요.
4. 같은 이름이 이미 있으면 편집…으로 기존 값을 바꿉니다. 각 창에서 확인을 눌러 저장합니다.
5. 모든 VS Code 창과 터미널 앱을 닫고 시작 메뉴에서 PowerShell을 새로 엽니다. 이미 실행 중인 앱에는 이전 환경이 남을 수 있습니다. 아래 검사에서 계속 Missing이 나오면 Windows에서 로그아웃 후 다시 로그인하거나 컴퓨터를 재시작합니다.
6. 새 PowerShell 창에서 다음 명령을 실행합니다. 값이 비어 있지 않은지만 표시하고 키 자체는 출력하지 않습니다.

if ($env:DTXWIKI_MCP_PAT) { 'Configured' } else { 'Missing' }

Configured는 이 PowerShell에서 값을 사용할 수 있다는 뜻이고, Missing은 값이 없다는 뜻입니다. 키가 올바른지 또는 아직 유효한지는 확인하지 않습니다. 컴퓨터를 재시작한 뒤에도 새 PowerShell에서 같은 검사를 해 보세요. CLI는 이 창에서 실행하고, VS Code도 저장한 사용자 환경을 받도록 실행합니다.

터미널에 $env:DTXWIKI_MCP_PAT = '...'만 입력하면 해당 프로세스에만 적용됩니다. 위 사용자 변수 창에서 저장해야 재시작 후에도 유지됩니다. Microsoft의 환경 변수 영구 저장 안내를 참고하세요.

macOS·Linux: 키 파일 저장과 시작 시 불러오기

터미널 명령을 해석하는 프로그램인 Bash 또는 Zsh를 기준으로 설명합니다. macOS의 터미널 또는 Linux의 터미널 앱을 엽니다. 각 명령 블록을 따로 실행하세요. 명령 앞에 프롬프트 표시인 $를 붙이지 않습니다.

1. 개인 파일 만들기

다음 명령으로 사용자 홈 폴더 아래에 폴더와 파일을 만듭니다. ~와 $HOME은 이 홈 폴더를 뜻합니다. 프로젝트 밖에 저장하는 파일입니다.

mkdir -p "$HOME/.config/dtxwiki"
chmod 700 "$HOME/.config/dtxwiki"
(umask 077; touch "$HOME/.config/dtxwiki/mcp-env")
chmod 600 "$HOME/.config/dtxwiki/mcp-env"
nano "$HOME/.config/dtxwiki/mcp-env"

nano는 터미널 안에서 사용하는 글 편집기입니다. 열린 파일에 다음 한 줄을 넣되, PASTE_YOUR_DTXWIKI_ACCESS_KEY_HERE 부분을 실제 키로 바꿉니다. 작은따옴표는 유지하고 = 앞뒤에 공백을 넣지 마세요.

export DTXWIKI_MCP_PAT='PASTE_YOUR_DTXWIKI_ACCESS_KEY_HERE'

Ctrl+O로 저장하고 Enter로 파일 이름을 확인한 다음 Ctrl+X로 나옵니다. macOS에서도 Control 키를 사용합니다. nano가 없다면 VS Code의 파일 → 파일 열기…에서 이 파일을 열어 같은 내용을 저장해도 됩니다. 키는 로컬 편집기에 입력하고 AI 채팅에는 붙여넣지 마세요.

권한 700과 600은 해당 폴더와 파일을 내 계정에서만 접근하게 합니다. 키를 암호화하거나 내 계정으로 실행하는 프로그램의 읽기를 막지는 않습니다. 파일에 같은 변수가 이미 있으면 줄을 추가하지 말고 기존 값을 수정하세요.

2. 새 터미널이 파일을 읽도록 설정하기

현재 터미널에서 사용하는 셸을 확인합니다.

ps -p $$ -o comm=

결과에 맞춰 시작 설정 파일을 선택합니다. 이름 앞에 -가 붙어도 정상입니다.

셸	편집할 시작 설정 파일
Zsh(zsh 또는 -zsh). 일반적인 macOS 기본값	~/.zshrc
Bash(bash 또는 -bash). Linux·WSL에서 주로 사용	~/.bashrc

nano ~/.zshrc 또는 nano ~/.bashrc로 해당 파일을 엽니다. 기존 내용을 유지하고 맨 아래에 다음 블록을 한 번만 추가한 뒤, 위와 같은 방법으로 저장하고 나옵니다.

if [ -f "$HOME/.config/dtxwiki/mcp-env" ]; then
  . "$HOME/.config/dtxwiki/mcp-env"
fi

점 뒤에 공백을 두고 파일 경로를 쓰는 명령은 “이 파일의 설정을 현재 셸에 불러오기”라는 뜻입니다. 이 블록에는 실제 키가 들어 있지 않습니다. 직접 만든 파일만 불러오세요.

macOS에서 Bash를 쓰는 경우를 포함해 Bash 로그인 터미널은 ~/.bash_profile, ~/.bash_login, ~/.profile 중 처음 존재하는 파일을 읽습니다. 해당 파일이 이미 ~/.bashrc를 불러오지 않는다면 같은 블록을 거기에도 넣으세요. 셋 다 없으면 ~/.bash_profile을 만들어 넣습니다. Zsh에서 ZDOTDIR을 따로 지정했다면 그 폴더의 .zshrc를 수정합니다. Bash 시작 규칙, Zsh 시작 규칙을 참고하세요.

3. 적용하고 키를 출력하지 않고 확인하기

현재 터미널에 파일을 불러옵니다.

. "$HOME/.config/dtxwiki/mcp-env"

이어서 확인합니다.

if [ -n "${DTXWIKI_MCP_PAT:-}" ]; then
  printf 'Configured\n'
else
  printf 'Missing\n'
fi

새 터미널 창을 열고 파일을 수동으로 불러오지 않은 상태에서 검사 명령만 다시 실행합니다. Configured가 나오면 값이 있고, Missing이면 없습니다. 다음 컴퓨터 재시작 후에도 반복해 보세요. Missing이면 지금 쓰는 셸에 맞는 시작 파일을 편집했는지 확인합니다. 진단 결과를 공유할 때는 키를 노출할 수 있는 echo "$DTXWIKI_MCP_PAT", printenv, 전체 환경 변수 출력은 피하세요.

값이 확인되면 CLI 사용자는 이 터미널에서 codex나 claude를 실행합니다. 저장한 키 파일을 모든 앱이 자동으로 읽는 것은 아닙니다. VS Code는 다음 절차를 따르세요.

변수가 준비된 상태에서 VS Code 실행

앱은 시작할 때 환경을 전달받습니다. VS Code 내장 터미널에서 변수를 설정해도 이미 실행 중인 확장에 거꾸로 전달되지는 않습니다. 두 번째 VS Code 창도 먼저 실행된 앱의 환경을 재사용할 수 있습니다. VS Code의 환경 상속 규칙을 참고하세요.

1. 작업을 저장하고 모든 VS Code 창을 완전히 종료합니다. macOS는 Code → Visual Studio Code 종료(Cmd+Q)를 사용합니다. 창만 닫으면 앱이 남아 있을 수 있습니다.
2. VS Code 밖의 터미널을 새로 엽니다. macOS/Linux는 위에서 설정한 셸을, Windows는 사용자 변수 저장 후 새로 연 PowerShell을 사용합니다. 위의 운영체제별 명령으로 Configured인지 확인하세요.
3. cd는 폴더를 이동하는 명령입니다. 아래 예시 경로를 프로젝트가 이미 있는 실제 폴더 경로로 바꾸고, 이동 후 code .을 실행하세요. 경로에 공백이 있으면 따옴표로 감쌉니다.

cd "$HOME/projects/my-project"
code .

점은 현재 폴더를 뜻하며, 이 명령은 PowerShell에서도 같습니다. macOS에서 code: command not found가 나오면 VS Code의 명령 팔레트(Cmd+Shift+P)에서 Shell Command: Install 'code' command in PATH를 실행합니다. 다시 VS Code를 완전히 종료하고 새 터미널을 여세요. VS Code 명령줄 설정을 참고하세요.

4. 확장 패널에서 새 대화를 시작합니다. MCP 서버 목록을 확인하고 dtxWiki 실제 읽기 검사를 진행하세요.

macOS/Linux에서 셸 파일 방식을 쓴다면 재시작 후에도 이 터미널 실행 절차를 따릅니다. 바탕 화면 아이콘으로 열면 다른 환경을 사용할 수 있습니다. 내장 터미널에서 Configured가 나오는 것만으로 확장도 변수를 받았다고 판단할 수는 없습니다.

WSL과 원격 개발

VS Code 왼쪽 아래에 WSL: Ubuntu나 SSH: …가 보이면 Linux 환경에서 프로젝트를 연 상태입니다. 확장 화면에서 AI 확장이 어디에 설치되어 실행되는지 확인하세요. 설정 파일과 변수도 그 환경에 있어야 합니다. Windows 사용자 변수만 설정해도 Linux에 같은 변수가 생기지는 않습니다.

WSL의 CLI는 WSL 안에서 macOS/Linux 절차를 완료합니다. WSL에서 실행하는 확장은 VS Code Server도 같은 키 파일을 읽도록 추가로 설정합니다.

1. WSL 터미널에서 mkdir -p "$HOME/.vscode-server"를 실행한 뒤 nano "$HOME/.vscode-server/server-env-setup"으로 파일을 엽니다.
2. 기존 설정을 유지하면서 다음 블록을 한 번만 추가하고 저장합니다. 일반 VS Code 기준이며, Insiders는 ~/.vscode-server-insiders/server-env-setup을 사용합니다.

if [ -f "$HOME/.config/dtxwiki/mcp-env" ]; then
  . "$HOME/.config/dtxwiki/mcp-env"
fi

3. 작업을 저장하고 VS Code의 WSL 창을 닫습니다. Windows를 재시작해 WSL과 VS Code Server를 새로 시작한 뒤 WSL에서 프로젝트를 다시 열고 실제 읽기를 확인합니다. 재부팅하지 않으려면 명령 팔레트에서 WSL: Kill VS Code Server를 사용할 수 있는 경우 실행한 뒤 다시 연결합니다.

WSL의 VS Code Server는 일반적인 셸 시작 파일을 실행하지 않으므로 이 실행 경로에는 .bashrc만으로 충분하지 않습니다. 공식 WSL 환경 설정 안내가 위 파일을 설명합니다. .env가 아닌 셸 스크립트이며 문법 오류가 있으면 서버가 시작되지 않을 수 있습니다. 문제가 생기면 일반 WSL 터미널에서 수정하거나 파일 이름을 바꾸세요. SSH 서버와 Dev Containers는 각각의 원격 환경 설정 방법을 따르고 변경 후 해당 환경의 확장 프로세스를 다시 시작합니다.

계속 실패하거나 키가 바뀌었을 때

증상	다음 확인
재시작 전에는 됐지만 지금은 Missing	Windows 사용자 변수를 저장하거나 셸 시작 블록을 추가합니다. MCP 등록만으로 값이 저장되지는 않습니다.
CLI는 되지만 VS Code 확장은 실패	모든 VS Code를 종료하고 변수가 준비된 외부 터미널에서 실행합니다. WSL·SSH에서는 확장의 실행 위치도 확인합니다.
프로젝트에 .env를 만들었지만 여전히 Missing	이 안내는 .env 자동 불러오기를 전제하지 않습니다. 위의 명시적인 설정 절차를 따릅니다.
Configured인데 인증 실패	값에 자리표시자, 따옴표, Bearer 없이 실제 키만 복사했는지 확인합니다. 이어서 설정 → MCP 접근에서 키 만료·해지 여부를 확인합니다.
키를 바꿨는데 앱이 이전 키를 사용	기존 Windows 변수나 키 파일의 값을 바꾸고 클라이언트와 VS Code를 완전히 다시 시작합니다. WSL 사용 시 서버도 다시 시작합니다.

값을 저장해도 키의 유효기간은 늘어나지 않습니다. dtxWiki 설정에서 만든 키는 90일 뒤 만료됩니다. 교체할 때는 필요한 워크스페이스 접근을 가진 새 키를 만들고, 저장한 값을 바꾸고, 앱을 다시 시작한 뒤 실제 읽기를 확인합니다. 이전 키가 아직 유효하면 확인 후 해지합니다.

로컬 저장을 해제하려면 Windows 사용자 변수 항목을 삭제하거나 개인 파일의 export DTXWIKI_MCP_PAT=... 줄을 지운 뒤 앱을 다시 시작합니다. 현재 터미널에서도 없애려면 Bash/Zsh는 unset DTXWIKI_MCP_PAT, PowerShell은 Remove-Item Env:DTXWIKI_MCP_PAT -ErrorAction SilentlyContinue를 실행합니다. 로컬 값을 지워도 서버의 키는 해지되지 않습니다. 더 이상 사용할 수 없게 하려면 설정 → MCP 접근에서 해지하세요.

AI 앱 연결로 돌아가 확장 설정을 마칩니다. 이 안내는 설정과 재시작 동작을 설명합니다. 실제로 설치한 클라이언트에서 자료 읽기를 확인한 뒤 연결을 사용하세요.