클로드 코드 클라우드 설정 — 저장소 것만 따라가고 스킬은 딴 길로

클라우드에서 세션을 띄웠는데 평소 쓰던 것들이 없습니다. 늘 부르던 명령이 없고, 붙여 둔 연결 도구도 안 보이고, 지시문도 안 먹는 것 같고요. 원인은 하나입니다 — 클라우드 세션은 저장소를 새로 복제해서 시작하기 때문입니다. 커밋해 둔 것만 따라가고, 내 기계에만 있는 건 안 갑니다.

그런데 이 규칙에 예외가 여럿입니다. 안 가는 줄 알았는데 계정을 거쳐 딴 길로 오는 것이 있고, 반대로 저장소에 커밋해 뒀는데도 조용히 무시되는 값이 있습니다. 어느 쪽인지 알아야 헛고생을 안 하니, 하나씩 갈라 보겠습니다.

📌 30초 요약

• 기준은 하나 — 저장소에 커밋했는가입니다.
• 스킬과 플러그인은 계정을 거쳐 따로 옵니다.
• 연결 도구는 추가한 범위에 따라 갈립니다.
• 일부 값은 무시되고 기록만 남습니다.

1. 기준은 커밋 여부 하나입니다

판단이 의외로 단순합니다. 복제본에 들어가느냐가 전부입니다. 저장소 안에 커밋해 둔 파일이면 그대로 따라가고, 내 홈 폴더에 둔 것이면 안 갑니다. 같은 이름의 설정이라도 어느 위치에 있느냐에 따라 결과가 갈린다는 뜻입니다.

무엇	클라우드에서
저장소의 지시문 파일	됨
저장소의 설정·훅·규칙	됨
저장소의 스킬·에이전트·명령	됨
내 홈의 지시문 파일	안 됨
내 홈의 스킬·에이전트·명령	안 됨(단서 있음)
조직의 서버 관리 설정	됨

마지막 줄에 함정이 하나 붙습니다. 조직 설정이라도 기기 관리 도구로 내 컴퓨터에 뿌려 둔 것은 적용되지 않습니다. 클라우드 세션이 도는 곳은 내 컴퓨터가 아니라 앤트로픽이 관리하는 가상 기계이기 때문입니다. 서버에서 내려 주는 쪽만 닿습니다. 회사에서 정책을 걸어 뒀는데 클라우드에서만 안 먹는다면 어느 경로로 배포됐는지부터 보셔야 합니다. 설정이 여러 곳에서 합쳐지는 방식은 따로 정리해 둔 글이 있습니다.

2. 안 가는데 딴 길로 오는 것들

표에서 「단서 있음」이라고 적은 줄이 여기입니다. 내 홈에 둔 스킬은 복제본에 안 들어가지만, 계정 쪽에서 켜 둔 스킬은 클라우드 세션이 알아서 불러옵니다. 파일이 따라가는 게 아니라 계정을 통해 별도 경로로 들어오는 겁니다. 플러그인도 같습니다 — 내 설정에만 켜 둔 것은 안 가지만, 계정에서 켜 두면 동기화되는 형태로 세션에 실립니다.

저장소 설정에 플러그인을 적어 두는 방법도 있는데, 이쪽은 성격이 다릅니다. 세션이 시작될 때 장터에서 내려받아 설치하므로 장터에 닿을 네트워크가 열려 있어야 합니다. 바깥 연결을 잠가 두셨다면 플러그인이 조용히 빠집니다. 이 부분은 바깥 연결 단계를 다룬 글과 함께 보시면 이유가 분명해집니다.

연결 도구 서버는 추가할 때 고른 범위가 그대로 결과를 가릅니다. 아무 옵션 없이 추가하면 내 기계의 개인 파일에 기록돼 클라우드에 안 갑니다. 프로젝트 범위로 지정해 추가하면 저장소 안의 설정 파일에 적히고, 그 파일을 커밋하면 따라갑니다. 「분명 붙여 뒀는데 클라우드에서만 없다」는 대부분 이 차이입니다.

3. 커밋했는데도 무시되는 값

반대 방향의 함정도 있습니다. 저장소 설정에 제대로 적어 커밋까지 했는데 클라우드에서는 안 먹는 값이 있습니다. 통신 경로를 다루는 값들이 여기 듭니다 — 사설 인증서 경로나 상호 인증에 쓰는 변수 같은 것들이죠.

⚠️ 오류도 경고도 없이 무시되고, 기록에만 남습니다

호스팅 환경이 세션의 연결을 직접 관리하기 때문에 클로드 코드가 이 값들을 그냥 건너뜁니다. 문제는 알려 주는 방식입니다 — 화면에 오류나 경고가 뜨지 않고, 무시한 항목 이름을 세션의 디버그 기록에만 적어 둡니다. 그래서 설정이 반영된 줄 알고 한참 헤매게 됩니다. 사내 인증서를 쓰는 환경에서 클라우드 세션이 이상하게 동작한다면 디버그 기록부터 열어 무시된 항목이 있는지 확인하세요.

무시되는 이유가 다른 경우도 하나 있습니다. 세션은 시작할 때 자기가 쓸 변수 몇 개를 스스로 정하는데, 그중 하나는 내가 적어 둔 값을 덮어씁니다. 대화가 길어졌을 때 자동으로 접는 비율을 정하는 값이 그렇습니다. 여기에 적어 봐야 효과가 없다는 뜻이라, 앞의 경우처럼 호스팅이 관리해서 건너뛰는 것과는 성격이 다릅니다. 둘 다 결과는 「적었는데 안 먹는다」로 같지만, 원인이 달라서 해결 방법도 달라집니다.

아예 불가능한 것도 하나 있습니다. 브라우저를 열어 로그인하는 방식의 인증은 클라우드 세션에서 쓸 수 없습니다. 클라우드 제공자의 통합 로그인이 대표적입니다. 세션 안에서 브라우저 창을 띄워 사람이 눌러 줄 수가 없으니 구조적으로 막힌 셈입니다. 그런 인증이 필요한 작업이라면 클라우드로 넘기지 마시고 내 기계에서 돌리는 편이 빠릅니다.

4. 열쇠는 어디에 두나

설정이 아니라 열쇠는 경로가 또 다릅니다. 저장소에 커밋할 수는 없으니 별도 자리가 필요한데, 요금제에 따라 갈립니다.

방식	성격
환경 자격증명	중계 서버가 요청이 나간 뒤 붙여 줌. 클로드도 명령도 값을 못 봄. 개인 유료 요금제만
환경 변수	붙일 수 없는 주소이거나 팀·기업 요금제일 때. 그 환경을 쓰는 사람이면 누구나 읽을 수 있음

아래 줄이 중요합니다. 환경 변수와 준비 스크립트는 그 환경을 쓰는 사람이면 누구나 읽습니다. 설정 화면에도 그 경고가 붙어 있고요. 공용 환경에 팀원 여럿이 들어와 있다면 환경 변수에 둔 열쇠는 사실상 공유된 것이라고 보셔야 합니다. 설정 키가 파일별로 어떻게 갈리는지는 정리해 둔 글을 함께 보시면 그림이 맞춰집니다.

환경 변수를 쓰실 때 걸리기 쉬운 것 둘을 적어 둡니다. 첫째, 세션은 시작할 때 값을 한 번만 복사해 갑니다. 돌고 있는 세션은 설정을 다시 읽지 않으므로, 값을 고쳐도 이미 떠 있는 세션은 옛 값을 그대로 씁니다. 새로 시작하는 세션부터 반영되는 겁니다. 준비 스크립트가 캐시 때문에 다시 안 도는 것과 같은 성질이라, 「고쳤는데 왜 그대로지」 싶으면 세션을 새로 띄워 보세요.

둘째는 형식입니다. 한 줄에 하나씩 이름과 값을 적는 흔한 방식인데, 값에 우물 정 기호가 들어가면 그 지점부터 주석으로 잘려 나갑니다. 따옴표로 감싸면 살아남고, 짝을 맞춰 감싼 따옴표는 값에 포함되지 않습니다. 여러 줄짜리 값도 마찬가지로 감싸야 합니다. 비밀번호나 연결 주소에 그 기호가 섞여 있는 경우가 의외로 많으니 값이 중간에 잘려 들어가지 않았는지 한 번 확인해 보세요.

끝으로 정리할 때 주의할 점 하나. 환경은 지울 수 없고 보관만 됩니다. 보관하면 선택 목록에서 사라져 새 세션을 못 띄우는데, 이미 돌고 있던 세션은 계속 동작하고 거기 등록해 둔 자격증명도 그대로 붙어 있습니다. 그러니 환경을 정리하실 거면 보관하기 전에 필요 없는 자격증명부터 지우는 순서가 맞습니다.

자주 묻는 질문 (FAQ)

Q. 늘 쓰던 명령이 클라우드에만 없습니다

내 홈 폴더에 두신 것 같습니다. 저장소 안으로 옮겨 커밋하면 따라갑니다. 스킬이라면 계정 쪽에서 켜 두는 방법도 있는데, 그 경우 파일이 가는 게 아니라 계정을 거쳐 별도로 실립니다.

Q. 연결 도구를 붙였는데 클라우드에서 안 보입니다

추가할 때 범위를 안 주셨을 가능성이 큽니다. 기본값이면 내 기계의 개인 파일에 기록됩니다. 프로젝트 범위로 다시 추가하면 저장소 안 설정 파일에 적히니, 그 파일을 커밋하세요.

Q. 사내 인증서 설정이 클라우드에서 안 먹습니다

의도된 동작입니다. 호스팅 환경이 연결을 직접 관리하므로 통신 경로 관련 값은 무시됩니다. 오류가 안 뜨고 디버그 기록에만 무시한 항목이 적히니 그쪽을 확인하세요. 그런 인증이 꼭 필요하면 내 기계에서 돌리는 게 맞습니다.

Q. 회사 정책이 클라우드 세션에만 적용이 안 됩니다

배포 경로를 보세요. 기기 관리 도구로 컴퓨터에 뿌린 설정은 클라우드에 적용되지 않습니다 — 세션이 도는 곳이 내 컴퓨터가 아니기 때문입니다. 서버에서 내려 주는 조직 설정은 세션 시작 때 정상적으로 받아 옵니다.

정리하면

• 기준은 커밋했는가 하나입니다.
• 스킬·플러그인은 계정을 거쳐 옵니다.
• 연결 도구는 프로젝트 범위로 추가하세요.
• 통신 경로 값은 말없이 무시됩니다.
• 환경 변수의 열쇠는 공유된 것입니다.

※ 공개된 클라우드 환경 설정 문서를 읽고 정리했습니다. 파일 경로와 설정 항목 이름은 우리말로 풀어 적었으니 실제 표기는 원문에서 확인하세요.

※ 요금제에 따라 되는 항목이 다르고 판올림에 따라 바뀝니다. 특히 팀·기업 요금제의 자격증명 등록은 아직 열리지 않은 상태라 나중에 달라질 수 있으니 원문과 대조해 확인하세요.