관리형 AI 에이전트 웹 접근 제한 — 조직 설정은 여기 안 먹습니다

에이전트에게 웹을 뒤지게 하면 "어디까지 가게 둘 것인가"를 정해야 합니다. 관리자라면 조직 설정에 한 번 걸어 두면 되겠지 싶은데, 문서에 짧게 박힌 안내가 그 기대를 깹니다 — 콘솔의 조직 단위 웹 설정은 관리형 에이전트 세션에 적용되지 않습니다. 에이전트마다 따로 걸어야 해요. 그 밖에 표기 규칙도 까다로워서, 잘못 적으면 저장 단계에서 거절당합니다.

📌 30초 요약

• ★★조직 콘솔 웹 설정은 여기 적용 안 됩니다 — 에이전트마다 따로요.
• ★도구 여덟 개가 기본으로 다 켜져 있습니다 — 끄려면 명시해야 해요.
• ★www 붙은 주소는 안 붙은 주소를 안 덮습니다.
• ⚠️ 여럿이 얽히면 허용 목록이 교집합 — 겹치는 게 없으면 전부 실패합니다.
• 채점자는 웹 도구 없이 돕니다 — 설정과 무관하게요.
• 출력이 아주 길면 파일로 떨어지고 모델은 미리보기만 받습니다.

도구는 기본으로 전부 켜집니다

기본 제공 도구는 여덟 가지입니다 — 명령 실행, 파일 읽기·쓰기·부분 수정, 이름으로 찾기, 내용으로 찾기, 웹 검색, 웹에서 가져오기. 묶음을 붙이면 여덟 개가 전부 켜진 상태로 시작합니다. 필요 없는 걸 끄려면 그 도구만 콕 집어 꺼야 해요.

반대 방식도 있습니다. 기본을 전부 꺼 두고 필요한 것만 켜는 설정이 따로 있어서, 보수적으로 시작하고 싶으면 그쪽이 낫습니다. 권한 모드를 골라 승인 범위를 정하던 방식과 결이 같은데, 여기서는 도구별로 "자동 승인이냐 물어보느냐"까지 각각 정할 수 있습니다.

알아 둘 동작이 하나 더 있습니다. 도구가 뱉은 결과가 십만 자쯤을 넘으면 자동으로 파일에 쓰이고, 모델은 잘린 미리보기와 파일 위치만 받습니다. 필요하면 그 파일을 읽어 가죠. 즉 긴 출력이 맥락을 통째로 잡아먹는 사고는 안 나지만, 모델이 전문을 봤다고 가정하면 안 됩니다.

조직 설정은 여기 안 먹습니다

관리자가 가장 놓치기 쉬운 대목입니다. 콘솔에서 조직 단위로 웹 검색·가져오기 정책을 걸어 뒀다면 그건 일반 요청에만 적용되고 관리형 에이전트 세션에는 안 걸립니다. 문서가 별도 안내로 못 박아 뒀어요.

🚨 한 번 걸어 두면 끝이라고 생각하면 안 됩니다

에이전트가 닿을 수 있는 사이트를 제한하려면 그 에이전트의 도구 설정에 허용 목록이나 차단 목록을 직접 넣어야 합니다. 검색과 가져오기는 각자 자기 목록을 갖기 때문에 따로 걸 수도 있고요. 또 하나 — 환경의 네트워크 설정을 조여도 이 두 도구는 영향을 안 받습니다. 제공사 서버에서 돌기 때문인데, 막는 유일한 방법이 이 목록이라는 뜻입니다.

허용 목록에 없는 주소를 가져오려 하면 오류 결과가 에이전트에게 돌아가고, 검색 쪽은 허용 안 된 결과를 조용히 빼고 내놓습니다. 막히는 방식이 서로 다르다는 것도 기억해 두세요.

도메인 표기 규칙이 까다롭습니다

목록에 적는 형식이 엄격합니다. 어기면 에이전트를 저장하는 시점에 거절되고, 몇 번째 항목이 왜 틀렸는지까지 알려 줍니다.

이렇게 쓰면	결과
주소 앞에 통신 규약을 붙이거나 포트를 적음	거절 — 이름만 적을 것
앞에 www 를 붙임	붙은 것만 덮습니다 — 안 붙은 주소는 별개
숫자 주소를 적음	거절 — 어떤 형태든 안 됩니다
최상위 이름만 적거나 사내 이름을 적음	거절 — 온전한 주소를 쓸 것
허용과 차단을 한 항목에 같이 씀	거절 — 둘 중 하나만
빈 목록을 넣음	거절 — 제한을 안 걸 거면 항목 자체를 빼라

가장 헷갈리는 건 둘째 줄입니다. 적어 둔 이름은 그 이름과 그 아래 하위 주소를 덮습니다. 그래서 회사 대표 주소를 적으면 그 아래 문서·블로그 주소까지 다 열리지만, 반대로 하위 주소를 적으면 위쪽이나 옆쪽 주소는 안 열립니다. 그리고 앞에 붙는 www 도 하위 주소 취급이라 둘 다 열고 싶으면 붙지 않은 이름을 적어야 합니다. 여러 서비스를 엮어 자동화를 짜 본 적이 있다면, 연동 대상 주소를 목록에 넣을 때 이 규칙부터 확인하세요. 목록 하나에 예순네 개까지 넣을 수 있습니다.

여럿이 얽히면 교집합이 됩니다

지휘 에이전트가 여럿을 부리는 구조에서는 규칙이 겹쳐 적용됩니다. 자기 목록, 자기를 부른 쪽의 목록, 지휘하는 쪽의 현재 목록이 전부 동시에 걸립니다. 방향은 한쪽뿐이에요 — 허용은 좁아지고 차단은 더해집니다. 아래에 있는 에이전트가 위에서 막아 둔 곳을 새로 열 수는 없습니다.

여기서 조용한 사고가 납니다. 합쳐 놓고 보니 공통으로 허용된 주소가 하나도 없으면, 도구는 여전히 붙어 있는데 부를 때마다 전부 실패합니다. 도구가 사라지는 게 아니라 살아 있는 채로 아무 데도 못 가는 상태가 되죠. 문서가 처방까지 적어 뒀습니다 — 아래쪽 목록을 위쪽 목록 안에 들어가게 유지할 것.

예외도 있습니다. 완료 기준을 채점하는 쪽은 설정과 무관하게 웹 도구 없이 돕니다. 그리고 가져올 분량 상한이나 검색 지역 같은 값은 합쳐지지 않고, 자기 설정이 있으면 그걸, 없으면 부른 쪽 것을, 그것도 없으면 지휘하는 쪽 것을 씁니다. 목록은 쉬고 있는 세션이면 도중에 바꿀 수 있고, 바꾼 값은 다음 차례부터 적용됩니다.

자주 묻는 질문 (FAQ)

Q. 한글 주소도 넣을 수 있나요?

그대로는 거절됩니다. 영문·숫자로 변환한 표기로 바꿔 넣어야 해요. 일반 요청 쪽은 한글 표기를 받아 주지만 여기서는 안 받습니다. 권장하지 않는다는 안내는 양쪽 다 붙어 있고요.

Q. 저장은 됐는데 세션에서 오류가 나요.

세션이 도구를 처음 준비할 때 한 번 더 확인하기 때문입니다. 저장 당시엔 괜찮았는데 그 사이 조건이 바뀌면 오류 신호를 내고 다시 시도하지 않은 채 멈춥니다. 세션 쪽 설정을 고치고 에이전트 쪽도 같이 고친 뒤 새 메시지를 보내야 이어집니다.

Q. 내가 만든 도구도 붙일 수 있나요?

됩니다. 모델은 요청만 만들고 실행은 내 코드가 합니다. 외부 서버의 기능을 통째로 붙일 거면 전용 연결 방식을 쓰라고 안내하고요. 자체 환경에서 돌린다면 사내망 안의 기능을 감싸 내보내는 방법도 있습니다.

Q. 도구 설명은 어떻게 쓰는 게 좋나요?

문서가 "이게 성능을 가르는 가장 큰 요인"이라고 단언합니다. 언제 쓰고 언제 쓰면 안 되는지까지 서너 문장으로 적으라고 하고요. 그리고 비슷한 동작은 여러 도구로 쪼개지 말고 하나로 묶으라고 권합니다 — 고를 게 많을수록 헷갈리니까요.

✨ 정리하면

조직에 한 번 걸어 두는 방식이 여기선 통하지 않습니다. 넷만 기억하세요 — 에이전트마다 목록을 직접 걸고, www 표기를 조심하고, 여럿이 얽히면 허용이 교집합이 되고, 환경 네트워크를 조여도 웹 도구는 안 막힙니다. 보수적으로 가려면 기본을 다 끄고 필요한 것만 켜는 쪽이 낫습니다. 비용과 권한을 함께 설계하는 흐름은 AI 지출 관리 허브에 정리해 두었습니다.

출처: Claude 공식 문서 「관리형 에이전트 도구」 (2026-09-02 열람). 시험 단계 기능이며 기본 도구 구성·상한·표기 규칙은 2026년 기준으로 변동될 수 있습니다.