AiAkiv CLI: 명령 한 줄로 폴더에 프로젝트 고정하기

AiAkiv CLI 는 터미널에서 명령으로 쓰는 도구다(CLI 는 명령줄 도구라는 뜻이다). npm 패키지 aiakiv 로 2026-10-18 에 처음 공개했고, 지금 판은 2026-10-24 에 낸 0.2.1 이다(이 문서는 0.2.1 판 기준이다. 0.2.1 은 0.2.0 에서 "다음 할 일" 안내 문구만 고쳤다). 설치하지 않고 npx aiakiv ... 로 바로 실행한다.

주된 일은 하나다. 작업 폴더에 AiAkiv 프로젝트를 고정한다. 그 폴더에서 실행한 AI 는 Main 을 바꿔도 늘 그 프로젝트로 읽고 쓴다. 폴더 고정이 무엇이고 왜 쓰는지는 폴더 바인딩에 있다.

무엇을 하고, 무엇을 하지 않나

폴더 고정에 쓰는 명령은 둘이다.

• bind: 폴더에 프로젝트를 고정한다. 웹 콘솔의 폴더 ZIP 받기와 같은 한 벌 (연결 설정 파일, AiAkiv 스킬 여덟 개 등)을 그 폴더에 직접 쓴다. ZIP 을 내려받지 않는다.
• doctor: 폴더 설정과 클라이언트 등록 상태를 확인하고 결과를 파일로 남긴다.

그 밖의 명령도 있다.

• setup: Gemini CLI 와 Antigravity 의 전역 설치(계정 연결과 전역 스킬)를 한다. 이 두 클라이언트만 받는다. 자세한 것은 아래 setup: Gemini CLI 와 Antigravity 전역 설치에 있다.
• console, dashboard: 터미널에서 웹 콘솔의 일(팀, 초대, 프로젝트, Main 전환, 연결, 카드)을 실행하고, 계정 상태를 한 화면으로 본다. 이 문서에서는 다루지 않는다. npx aiakiv --help 와 npx aiakiv console describe 가 할 수 있는 일을 보여 준다.

CLI 가 하지 않는 일도 있다.

• Gemini CLI 와 Antigravity 가 아닌 클라이언트의 전역 설치는 하지 않는다. 계정 연결, 플러그인, 전역 스킬은 지금까지의 방법 그대로 한다. Claude Code 는 플러그인 마켓 (계정 커넥터나 플러그인), Codex 는 Codex 설치 프롬프트, ChatGPT 는 플러그인 디렉터리(ChatGPT 연결), Cursor 는 홈페이지의 설치 링크로 붙인다. Grok 은 웹 커넥터 화면에서 붙인다. setup --client claude 처럼 다른 클라이언트를 주면 이 안내만 보여 주고 아무것도 하지 않는다(종료 코드 2).
• 키 목록 보기와 폐기는 웹 콘솔에서 한다. bind 와 setup 은 새 키를 받을 때 앞선 키가 폐기되는 것 말고는 키를 정리하지 않는다. console key 도 관리 작업용 계정 키를 받아 쓸 뿐이다.
• 로그인 정보를 따로 저장하지 않는다. CLI 에는 login 명령이 없다. bind 와 setup 이 받은 키는 그 클라이언트의 설정 파일에만 쓴다. console key 가 받는 관리용 계정 키는 그 폴더의 .aiakiv/console.json 에 쓴다. 그 밖에 CLI 가 토큰이나 키를 따로 두는 곳은 없다.

준비물

• Node.js 18.3 이상(npx 가 함께 들어 있다). 없으면 설치한다.
  • Windows: winget install OpenJS.NodeJS.LTS
  • macOS: brew install node
  • Linux: 배포판 패키지(예: sudo apt install nodejs npm) 또는 nvm
• AiAkiv 계정과, 웹 콘솔(app.aiakiv.com)에 로그인할 수 있는 브라우저.
• 고정할 폴더. 폴더가 이미 있어야 한다. CLI 가 폴더를 만들지는 않는다.
• Claude Code 와 Cursor 는 프로젝트가 웹 콘솔에 먼저 있어야 한다. Codex 와 Gemini CLI 는 없어도 된다. 확인 화면에서 만들 수 있다.

처음 실행하면 npx 가 패키지를 받을지 묻는다. y 로 답하거나, 처음부터 npx -y aiakiv ... 로 실행한다.

명령과 옵션

npx aiakiv bind   --client codex|claude|gemini|cursor --project <이름> [--dir <폴더>] [--expires-days N] [--no-browser] [--no-skills]
npx aiakiv setup  --client gemini|antigravity[,...] [--expires-days N] [--no-browser] [--no-skills] [--new-key]
npx aiakiv doctor [--client <클라이언트>[,...]] [--dir <폴더>] [--out aiakiv-verification-test.md] [--no-probe]

클라이언트별 사용법

어느 클라이언트든 순서는 같다. bind 를 실행하고, 사람이 로그인이나 확인 버튼을 누르고, 그 폴더에서 클라이언트를 열어 저장 대상을 확인한다. 클라이언트마다 다른 것은 인증 방식이다. Claude Code 와 Cursor 는 로그인(OAuth) 연결이라 키를 받지 않고, Codex 와 Gemini CLI 는 프로젝트에 묶인 키를 받아 설정 파일에 넣는다.

Claude Code

npx aiakiv bind --client claude --project myproject --dir ./my-work

CLI 가 폴더에 .mcp.json(서버 이름 AiAkiv-myproject, 주소 https://mcp.aiakiv.com/mcp?project=myproject)을 쓰고, .claude/settings.json 에 이 서버를 미리 켜 두고, 스킬 여덟 개를 .claude/skills/ 에 넣는다.

사람이 할 일:

1. 그 폴더에서 claude 를 실행한다. 이 폴더를 신뢰하겠냐고 물으면 신뢰한다고 답한다. 서버를 승인할지는 따로 묻지 않는다. CLI 가 미리 켜 두었기 때문이다(2026-10-18 Claude Code 2.1.302 에서 확인).
2. /mcp 에서 AiAkiv-myproject 를 골라 브라우저로 로그인한다.
3. "저장 대상 확인해 줘" 라고 묻는다. binding 이 folder 이고 프로젝트가 myproject 면 끝이다.

Claude Desktop 의 </> Code 도 같은 .mcp.json 을 읽는다. 다만 CLI 로 고정한 폴더를 Desktop 에서 여는 경우는 아직 확인하지 않았다. 먼저 터미널에서 claude 를 실행해 로그인까지 끝내 두고, Desktop 에서 저장 대상을 확인한다. 자세한 것은 Claude Desktop에 있다.

Cursor

npx aiakiv bind --client cursor --project myproject --dir ./my-work

CLI 가 .cursor/mcp.json 에 같은 ?project= 주소를 쓰고, 스킬 여덟 개를 .agents/skills/ 에 넣는다. 사람이 할 일은 이렇다.

1. Cursor 로 그 폴더를 연다.
2. Cursor 설정(Ctrl+Shift+J)의 Tools & MCP 화면에서 AiAkiv-myproject 를 켠다. Cursor 는 폴더에 든 서버를 사람이 한 번 켜기 전에는 연결하지 않고, 로그인도 묻지 않는다.
3. 켜면 로그인하라는 표시가 나온다. 누르고 브라우저에서 로그인한다.
4. 새 채팅에서 "저장 대상 확인해 줘" 라고 물어 binding 이 folder 인지 본다.

Cursor 전역 설정(~/.cursor/mcp.json)에 Main 을 따라가는 AiAkiv 연결이 이미 있으면, AI 가 그쪽을 부를 수 있다. 이때는 "AiAkiv-myproject 로 저장 대상 확인해 줘" 처럼 서버 이름을 지목하면 폴더 연결로 간다.

Cursor 는 2026-10-24 에 확인했다. Tools & MCP 에서 폴더 서버를 켜자 로그인을 거쳐 연결됐고, 서버 이름을 지목하면 폴더 연결로 답했다. .agents/skills/ 의 스킬 여덟 개도 Cursor 에 보였다.

Codex 와 Gemini CLI

npx aiakiv bind --client codex --project myproject --dir ./my-work
npx aiakiv bind --client gemini --project myproject --dir ./my-work

CLI 는 이 둘에 프로젝트에 묶인 API 키를 쓴다(연결 인증). 콘솔에서 키를 발급해 손으로 붙여 넣는 대신, CLI 가 키를 받아 설정 파일에 바로 써 준다.

Codex 는 로그인(OAuth) 방식으로도 폴더를 고정할 수 있다. 다만 지금 판(0.2.1)의 CLI 는 Codex 에 키 방식만 쓴다. 로그인 방식으로 하려면 설정을 손으로 넣는다. 방법은 ChatGPT 연결 §2 방법 A 에 있다. Gemini CLI 는 로그인 세션이 유지되지 않아 키 방식만 쓴다.

1. CLI 가 브라우저로 웹 콘솔의 확인 화면을 연다. 로그인이 안 돼 있으면 로그인 화면을 거쳐 돌아온다.
2. 사람이 확인 버튼을 누른다.
   • 프로젝트가 있으면 "CLI 에 키 넘기기" 화면이 나온다. [예, 넘깁니다] 를 누른다.
   • 프로젝트가 없으면 "프로젝트를 만들고 키를 넘길까요?" 화면이 나온다. 팀을 고르고 (개인 팀이 먼저 골라져 있다) [만들고 넘깁니다] 를 누른다.
   • 어느 화면에도 키는 나오지 않는다.
3. 브라우저가 "CLI 로 돌아가세요" 를 띄우면 탭을 닫아도 된다. 터미널에 키 번호(키 id), 팀, 서버 이름, 설정 파일 경로가 나온다. 키 자체는 화면에 출력하지 않고 설정 파일에만 쓴다.
4. Codex 는 그 폴더에서 codex 를 실행하고, 이 폴더를 신뢰하겠냐고 물으면 신뢰한다고 답한다. 앱은 다시 시작한다. Gemini 는 그 폴더에서 gemini 를 실행한다.
5. npx aiakiv doctor --dir ./my-work 로 확인한다(아래). binding 이 api-key 이고 프로젝트가 myproject 면 끝이다.

알아 둘 것:

• 확인은 5분 안에 해야 한다. 5분이 지나면 CLI 가 끝나니 같은 명령을 다시 실행한다.
• 키는 읽기와 쓰기만 된다. AI 에게 콘솔 관리 일을 시키는 권한(manage)은 없다. 그 권한이 필요하면 웹 콘솔에서 "AI 콘솔 관리 허용 (manage)" 을 체크해 키를 발급한다 (연결 인증).
• 한 프로젝트에 살아 있는 키는 하나다. 같은 프로젝트의 키를 새로 받으면, 다른 폴더나 다른 클라이언트에서 받았든 웹 콘솔에서 발급했든, 그 프로젝트의 이전 키는 폐기된다. 확인 화면에도 이 경고가 나오고, 폐기했으면 터미널에 "이전 키 N개를 폐기했습니다" 가 나온다. 그래서 같은 프로젝트를 키로 두 폴더에 고정하면 마지막에 받은 폴더만 동작한다. Claude Code 와 Cursor 의 로그인 연결은 키를 쓰지 않아 이 제한과 상관없다.
• --no-browser 는 브라우저를 열지 않고 확인 화면 주소만 출력한다. 그 주소를 이 PC 의 다른 브라우저(이미 로그인해 둔 브라우저 등)에서 연다. 확인 버튼을 누르면 브라우저가 이 PC 안의 CLI(127.0.0.1)로 돌아오므로, 다른 기기에서 열면 CLI 가 키를 받지 못한다.
• 확인 화면은 지금 한국어로만 나온다.
• Codex 는 2026-10-18 에 0.1.0 으로 확인했다(키 연결, .agents/skills 의 스킬 일곱 개 읽기, binding api-key). 그때는 aiakiv-dashboard 가 더해지기 전이라 스킬이 일곱 개였다. Gemini CLI 는 CLI 가 폴더 설정 파일을 쓰는 것까지 확인했고, 폴더를 고정한 Gemini CLI 안에서 쓰는 것은 아직 확인하지 않았다. setup 의 전역 연결은 Gemini CLI 안에서 확인했다(아래 setup 절).

폴더에 생기는 파일

• 이미 있는 파일은 같은 이름의 항목만 바꾼다. 다른 서버와 다른 설정은 그대로 둔다.
• 주석이나 끝 쉼표가 있는 JSON 파일은 표준 JSON 으로 다시 쓰면서 원본을 <파일>.aiakiv-backup 으로 남긴다. 원본에 예전 키가 들어 있을 수 있으니 확인한 뒤 지운다. .codex/config.toml 에서 같은 이름의 항목을 바꿀 때는 그 파일의 주석이 사라진다(값은 남는다). 두 경우 모두 터미널에 알린다.
• 스킬 여덟 개는 aiakiv-onboarding, aiakiv-save-and-recall, aiakiv-graph-query, aiakiv-links, aiakiv-cards, aiakiv-console, aiakiv-contents, aiakiv-dashboard 다. 공개 저장소 github.com/AiAkiv/aiakiv-plugins 에서 받는다. 같은 이름의 스킬 폴더는 통째로 바꾸고, 다른 스킬은 건드리지 않는다. 전역 스킬이 이미 있어도 내용이 같아 동작에는 문제가 없고, 목록에 두 번 보일 뿐이다.
• 서버 이름은 콘솔과 같은 규칙(AiAkiv-<프로젝트 이름>)으로 짓는다 (ChatGPT 연결 §4). 다만 Claude Code 와 Cursor 는 키를 받지 않아 프로젝트 id 를 모르므로, 영문이 아닌 글자가 든 이름이나 긴 이름이면 콘솔이 붙이는 짧은 코드 대신 이름에서 만든 다른 코드를 붙인다. 이름이 콘솔과 달라질 뿐 동작은 같다. 영문 19자 이내의 이름은 콘솔과 똑같다.

setup: Gemini CLI 와 Antigravity 전역 설치

npx aiakiv setup --client gemini
npx aiakiv setup --client antigravity
npx aiakiv setup --client gemini,antigravity

setup 은 폴더가 아니라 계정 전체 연결을 만든다. Gemini CLI 와 Antigravity 두 클라이언트만 받는다. 둘은 API 키로만 붙는 클라이언트라(연결 인증) 콘솔에서 키를 발급해 손으로 붙여 넣어야 했는데, 그 일을 setup 이 대신한다.

1. CLI 가 이 PC 의 127.0.0.1 에 임시 포트를 열고, 브라우저로 웹 콘솔의 "계정 전체 연결용 기억 키 넘기기" 화면을 연다. 로그인이 안 돼 있으면 로그인 화면을 거쳐 돌아온다.
2. 사람이 만료 일을 정하고 [예, 넘깁니다] 버튼을 누른다. CLI 는 최대 5분 기다리고, 그 안에 누르지 않으면 끝난다. --no-browser 로 받은 주소도 같은 PC 의 브라우저에서만 열 수 있다. 이 두 가지는 bind 와 같다.
3. CLI 가 Main(저장 대상)을 따라가는 계정 전체 키 하나를 받아, 고른 클라이언트 모두의 전역 설정 파일에 바로 쓴다. 평문 키는 화면에도 터미널에도 나오지 않고, 터미널에는 키 번호(키 id)만 나온다. 서버 이름은 AiAkiv, 주소는 https://mcp.aiakiv.com/mcp 다. 폴더 연결의 AiAkiv-<프로젝트> 와 겹치지 않는다.
4. 전역 스킬 여덟 개를 쓴다(--no-skills 면 건너뛴다).
5. 마지막 줄에서 키 평문이 든 설정 파일을 공유하거나 커밋하지 말라고 경고한다.

이미 있는 파일은 지킨다. AiAkiv 항목만 더하거나 바꾸고, 다른 서버와 다른 설정은 그대로 둔다. 주석이 있는 JSON 파일이면 원본을 <파일>.aiakiv-backup 으로 남긴다.

사람이 할 일:

• Gemini CLI: 작업 폴더에서 gemini 를 실행한다. 처음 여는 폴더면 이 폴더를 신뢰하겠냐고 묻는다. 신뢰한다고 답한다. Gemini CLI 는 신뢰하지 않은 폴더에서는 전역 서버도 "Disabled" 로 보여 준다. 그다음 그 폴더에서 gemini mcp list 를 실행해 AiAkiv … Connected 가 나오는지 본다. Gemini CLI 대화 안의 /mcp 로도 볼 수 있다.
• Antigravity: 앱이 켜져 있었다면 설정 파일을 바꿨으니 다시 시작한다. 서버 목록은 왼쪽 사이드바의 Skills & Customizations 나 대화 화면의 더보기(...) 메뉴 > MCP Servers 에서 볼 수 있다. Antigravity 는 MCP 도구를 미리 펼쳐 보여 주지 않고 에이전트가 필요할 때 꺼내 쓰므로, 목록에서 도구가 바로 안 보여도 새 대화에서 물어보면 된다.
• 두 클라이언트 모두 새 대화에서 "저장 대상 확인해 줘" 라고 물어 binding 이 main 인지 본다.

Gemini CLI 는 2026-10-24 에 Gemini CLI 0.49.0 으로 확인했다. setup 이 쓴 settings.json 을 Gemini CLI 가 읽었고, gemini mcp list 에 Connected 가 나왔고, 그 키로 저장 대상을 물으면 binding 이 main 이었다. Antigravity 는 같은 날 Antigravity 2.26.0 으로 확인했다. 앱을 다시 시작하자 설정 파일을 읽어 AiAkiv 도구를 받았고, 새 대화에서 저장 대상을 물으면 답이 왔고, 전역 스킬 여덟 개도 앱에 보였다.

알아 둘 것:

• 계정 전체 키는 한 사람에게 하나만 살아 있다. 이 키는 프로젝트에 묶이지 않고 Main 을 따라가며, 기억 읽기와 쓰기만 된다. 팀 만들기 같은 관리 작업은 못 한다. 새로 받으면 앞선 계정 전체 키는 폐기된다. 다른 PC 에 넣어 둔 키와 웹 콘솔에서 받은 키도 마찬가지다.
• 같은 PC 에서는 키를 다시 쓴다. setup 은 먼저 이 PC 의 두 전역 파일에서 AiAkiv 항목의 키를 찾아 불러 본다. 키가 살아 있고 binding 이 main 이면 브라우저를 열지 않고 그 키를 다시 쓴다. 그래서 --client gemini 를 한 뒤 --client antigravity 를 따로 해도 앞선 키가 폐기되지 않는다. 꼭 새 키가 필요하면 --new-key 를 준다.
• PC 를 여러 대 쓰면 조심한다. 다른 PC 에는 다시 쓸 키가 없으니 PC 마다 setup 을 따로 해야 하고, 그때마다 새 키를 받는다. 그러면 앞 PC 의 키가 폐기되어 그 PC 의 Gemini CLI 와 Antigravity 는 인증 오류(401)가 난다. 계정 전체 키로 붙인 전역 연결은 한 번에 PC 한 대에서만 동작한다고 보면 된다. 앞 PC 를 다시 쓰려면 그 PC 에서 setup 을 다시 하고, 그러면 이번에는 다른 PC 의 키가 폐기된다.
• 키를 새로 받으면 키 번호(키 id)와 키의 지문(키에서 만든 짧은 확인 값)만 ~/.gemini/aiakiv-setup.json 에 적어 둔다. 키 자체는 거기에 없다.
• 전역 설정 파일은 홈 폴더에 있어 .gitignore 로 뺄 수 없다. 공유하거나 저장소에 올리지 않는다.
• 끝나면 npx aiakiv doctor --client gemini,antigravity 로 확인한다. 전역 AiAkiv 연결은 binding 이 main 이어야 한다. 401 이면 setup 을 다시 하고, main 이 아니면 --new-key 로 다시 받는다.
• Antigravity 는 앱 전체에 설정 파일이 하나라 폴더 고정이 없다. bind --client antigravity 는 사용 오류이고, setup --client antigravity 를 쓴다.
• 다른 클라이언트의 전역 설치는 setup 으로 하지 않는다. 방법은 위 무엇을 하고, 무엇을 하지 않나에 있다.

doctor 로 확인하기

npx aiakiv doctor --dir ./my-work

doctor 는 그 폴더의 설정 파일, 전역 설정 파일(~/.cursor/mcp.json, ~/.gemini/settings.json, Antigravity 의 ~/.gemini/config/mcp_config.json), 클라이언트에 등록된 AiAkiv 연결 (claude, codex 명령이 있으면), 스킬이 들어 있는 폴더를 살펴 결과를 aiakiv-verification-test.md 에 쓴다. 폴더 연결과 함께 붙어 있는 전역 연결도 적어 두어 겹치는 연결을 알아볼 수 있다.

• 키 연결(Codex, Gemini CLI) 은 doctor 가 저장 대상 확인(get_save_target)을 직접 불러 팀, 프로젝트, binding 을 적는다. 키가 폐기됐으면 연결이 거절되고(401), 그 폴더에서 bind 를 다시 하라고 안내한다. 키 연결이 실패하면 doctor 는 오류 코드 1 로 끝난다.
• 로그인 연결(Claude Code, Cursor) 은 로그인이 필요해 doctor 가 직접 확인하지 못한다. 클라이언트 안에서 "저장 대상 확인해 줘" 라고 물어 binding 이 folder 인지 본다.
• setup 이 쓴 전역 AiAkiv 연결(Gemini CLI, Antigravity) 도 doctor 가 직접 불러 본다. binding 이 main 이어야 한다. 401 이면 setup 을 다시 하라고, main 이 아니면 --new-key 로 다시 받으라고 적는다.
• 스킬 여덟 개가 다 들어 있는지도 적는다. 빠진 것이 있으면 다시 할 일을 적는다.

결과 파일에는 키의 앞 8자만 적힌다. 그래도 저장소에 올릴 필요는 없다.

결과 확인 기준

폴더에서 main 이 나오면 폴더 연결이 아니라 Main 을 따르는 연결을 부른 것이다. 계정 커넥터나 플러그인, setup 의 전역 연결이 함께 붙어 있으면 생긴다. 계정 커넥터와 폴더 연결이 함께 있을 때와 ChatGPT 연결 §4 를 본다.

AI 에게 시키기

CLI 는 AI 가 대신 실행해도 된다. 대화창에 이렇게 부탁하면 된다.

이 폴더에 AiAkiv 프로젝트 myproject 를 고정해 줘.
npx aiakiv bind --client codex --project myproject 를 실행하고, 확인 버튼은 내가 누를게.
끝나면 npx aiakiv doctor 로 확인해 줘.

다만 지킬 것이 있다.

• 확인 버튼(Codex 와 Gemini CLI 의 bind, 그리고 setup)과 로그인(Claude Code, Cursor)은 사람이 한다. AI 가 브라우저를 대신 조작하게 하지 않는다.
• AI 의 명령 실행 시간 제한이 5분보다 짧으면 CLI 가 기다리는 도중에 끊길 수 있다. 그때는 사람이 터미널에서 같은 명령을 직접 실행한다.
• AI 에게 키가 든 설정 파일을 읽히지 않는다. CLI 출력(키 번호, 서버 이름, 파일 경로) 만 보여 주면 충분하다.

AI 가 CLI 를 대신 실행하는 경우는 아직 실제로 돌려 보지 않았다.

문제 해결

• 로그인이 안 된다.

  • Claude Code: /mcp 에서 그 서버를 다시 골라 로그인한다. 브라우저에 로그인된 계정이 그 프로젝트가 있는 계정인지 본다.
  • Codex, Gemini CLI, setup: 브라우저가 열리지 않았으면 터미널에 나온 주소를 같은 PC 의 브라우저에서 직접 연다. "요청을 확인할 수 없습니다" 가 나오면 명령을 다시 실행한다.

• 5분이 지났다, 확인 코드가 만료됐다. bind 와 setup 모두 최대 5분 기다리고 끝난다. 같은 명령을 다시 실행한다. 확인 화면도 새로 열린다.

• 스킬을 받지 못했다. 연결 설정은 이미 썼으니 bind 는 실패로 끝나지 않는다. 대신 터미널에 직접 칠 명령이 나온다. 그 폴더에서 실행한다.

  npx -y skills add AiAkiv/aiakiv-plugins -a <에이전트> -s '*' -y
  

  <에이전트> 는 claude-code, codex, gemini-cli, cursor 가운데 하나다. 전역에 넣는 -g 와 모든 에이전트 폴더에 퍼뜨리는 --all 은 붙이지 않는다. 같은 bind 를 다시 실행해도 된다. setup 에서 받지 못했으면 터미널에 나온 안내를 따른다(Gemini CLI 는 -g 가 붙은 명령이, Antigravity 는 스킬 폴더를 직접 복사하라는 안내가 나온다).

• Gemini CLI 에서 AiAkiv 가 "Disabled" 로 보인다. 지금 폴더를 신뢰하지 않은 상태다. Gemini CLI 는 신뢰하지 않은 폴더에서는 setup 이 넣은 전역 서버도 끈다. 그 폴더를 신뢰한 뒤 gemini mcp list 를 다시 실행해 AiAkiv … Connected 를 확인한다.

• 키가 폐기됐다. doctor 가 401 을 보고하거나, 도구를 부를 때마다 인증 오류가 난다.

  • bind 로 고정한 폴더: 같은 프로젝트의 키를 다른 곳에서 새로 받은 경우다. 이 폴더에서 bind 를 다시 한다.
  • setup 의 전역 연결: 다른 PC 에서 setup 을 했거나, 웹 콘솔에서 계정 전체 키를 새로 받은 경우다. 계정 전체 키는 한 사람에게 하나라서 이 PC 의 키가 폐기됐다. 이 PC 에서 setup 을 다시 하면 되지만, 그러면 이번에는 다른 PC 의 키가 폐기된다.

• 프로젝트 이름을 잘못 적었다.

  • Codex, Gemini CLI: 있는 프로젝트인데 "프로젝트를 만들고 키를 넘길까요?" 가 나오면 이름이 틀린 것이다. [아니요] 를 누르고 이름을 고쳐 다시 실행한다. 이미 잘못된 이름으로 만들었으면 웹 콘솔에서 정리한다.
  • Claude Code, Cursor: CLI 는 프로젝트가 있는지 확인하지 않는다. 틀린 이름이면 연결은 되지만 도구를 부를 때마다 막힌다. 바른 이름으로 bind 를 다시 하고, 틀린 이름으로 생긴 서버 항목(AiAkiv-<틀린 이름>)을 .mcp.json(Cursor 는 .cursor/mcp.json)에서 지운다. Claude Code 는 .claude/settings.json 의 enabledMcpjsonServers 에서도 지운다.

• "이 프로젝트의 키는 넘길 수 없습니다" 가 나온다. 그 프로젝트가 내가 구성원이 아닌 팀을 가리킨다. 웹 콘솔에서 프로젝트를 확인한다.

• setup --client claude 가 안내만 보여 주고 끝난다. 정상이다. setup 은 Gemini CLI 와 Antigravity 만 받는다. 다른 클라이언트의 전역 설치는 위 무엇을 하고, 무엇을 하지 않나의 방법으로 한다.

• bind --client antigravity 가 사용 오류라고 나온다. Antigravity 는 폴더 고정이 없다. npx aiakiv setup --client antigravity 를 쓴다.

• setup 명령이 없다고 나온다. 0.1.0 이 실행된 것이다. setup 은 0.2.0 부터 있다. npx [email protected] setup --client gemini 처럼 판을 적어 실행한다.

보안

• 키가 든 설정 파일은 저장소에 올리지 않는다. .codex/config.toml, .gemini/settings.json 이다. 폴더가 git 저장소이거나 .gitignore 가 있으면 CLI 가 .gitignore 에 스스로 더한다. 둘 다 아니면 경고만 하니 직접 챙긴다.
• setup 이 쓰는 전역 설정 파일에도 평문 키가 든다. ~/.gemini/settings.json, ~/.gemini/config/mcp_config.json 이다. 홈 폴더라 .gitignore 로 뺄 수 없으니 공유하거나 저장소에 올리지 않는다. CLI 도 마지막 줄에서 이렇게 경고한다. 기록 파일 ~/.gemini/aiakiv-setup.json 에는 키 번호와 지문 일부만 있고 평문 키는 없다.
• AI 에게 키 파일 내용을 읽히지 않는다. 대화창, 이슈, 문서에도 붙여 넣지 않는다.
• CLI 는 키를 화면, 로그, 오류 문구에 내지 않는다. doctor 결과 파일에는 앞 8자만 적는다.
• <파일>.aiakiv-backup 이 생겼으면 예전 키가 들어 있을 수 있다. 확인한 뒤 지운다.
• macOS 와 Linux 에서는 키가 든 설정 파일을 그 사용자만 읽을 수 있게 쓴다.
• 키가 새어 나간 것 같으면 웹 콘솔에서 폐기하거나 bind 를 다시 한다(setup 의 계정 전체 키는 setup --new-key). 같은 프로젝트의 키를 새로 받으면 이전 키는 폐기된다. 키 보안의 최소선 전체는 연결 인증의 키 보안에 있다.

관련 문서

• 폴더 고정이 무엇이고 binding 값을 어떻게 읽나: 폴더 바인딩
• 로그인 연결과 API 키의 차이: 연결 인증
• ChatGPT 와 Codex 의 연결 방법, 서버 이름 규칙: ChatGPT 연결
• Codex 전역 설치: Codex 설치 프롬프트
• Claude 에서 AiAkiv 가 두 개로 보일 때: 계정 커넥터와 폴더 연결이 함께 있을 때