Documentation 2026-10-29 23:57 UTC to 2026-10-30 23:01 UTC

77* **Python:** `claude_agent_sdk`에서 가져온 클래스에 대해 `isinstance()`로 메시지 타입을 확인합니다(예: `isinstance(message, ResultMessage)`).77* **Python:** `claude_agent_sdk`에서 가져온 클래스에 대해 `isinstance()`로 메시지 타입을 확인합니다(예: `isinstance(message, ResultMessage)`).

78* **TypeScript:** `type` 문자열 필드를 확인합니다(예: `message.type === "result"`). `AssistantMessage`와 `UserMessage`는 원본 API 메시지를 `.message` 필드에 래핑하므로 콘텐츠 블록은 `message.content`가 아니라 `message.message.content`에 있습니다.78* **TypeScript:** `type` 문자열 필드를 확인합니다(예: `message.type === "result"`). `AssistantMessage`와 `UserMessage`는 원본 API 메시지를 `.message` 필드에 래핑하므로 콘텐츠 블록은 `message.content`가 아니라 `message.message.content`에 있습니다.

79 79 

80> **예제: 메시지 타입 확인 및 결과 처리**80> [accordion] 예제: 메시지 타입 확인 및 결과 처리

81>81>

82> ```python Python theme={null}82> ```python Python theme={null}

83> import asyncio83> import asyncio

273* **`PreCompact` 훅:** 압축 전에 사용자 정의 로직을 실행합니다(예: 전체 트랜스크립트를 보관). 훅은 `trigger` 필드(`manual` 또는 `auto`)를 받습니다. [훅](https://code.claude.com/docs/ko/agent-sdk/hooks.md)을 참조하세요.273* **`PreCompact` 훅:** 압축 전에 사용자 정의 로직을 실행합니다(예: 전체 트랜스크립트를 보관). 훅은 `trigger` 필드(`manual` 또는 `auto`)를 받습니다. [훅](https://code.claude.com/docs/ko/agent-sdk/hooks.md)을 참조하세요.

274* **수동 압축:** `/compact`를 프롬프트 문자열로 보내 필요에 따라 압축을 트리거합니다. 이 방식으로 전송된 명령은 일반적인 SDK 입력입니다. [이름으로 명령 디스패치](https://code.claude.com/docs/ko/agent-sdk/skills.md#dispatch-commands-by-name)를 참조하세요.274* **수동 압축:** `/compact`를 프롬프트 문자열로 보내 필요에 따라 압축을 트리거합니다. 이 방식으로 전송된 명령은 일반적인 SDK 입력입니다. [이름으로 명령 디스패치](https://code.claude.com/docs/ko/agent-sdk/skills.md#dispatch-commands-by-name)를 참조하세요.

275 275 

276> **예제: CLAUDE.md의 요약 지침**276> [accordion] 예제: CLAUDE.md의 요약 지침

277>277>

278> 프로젝트의 CLAUDE.md에 섹션을 추가하여 압축기에 보존할 내용을 알립니다. 헤더 이름은 특별하지 않습니다; 명확한 레이블을 사용합니다.278> 프로젝트의 CLAUDE.md에 섹션을 추가하여 압축기에 보존할 내용을 알립니다. 헤더 이름은 특별하지 않습니다; 명확한 레이블을 사용합니다.

279>279>

42 42 

43이 페이지에서 HTTP 요청을 수행하는 Python 예제는 [httpx](https://www.python-httpx.org/)를 사용합니다. 프로젝트에서 사용하는 패키지 관리자로 추가하세요:43이 페이지에서 HTTP 요청을 수행하는 Python 예제는 [httpx](https://www.python-httpx.org/)를 사용합니다. 프로젝트에서 사용하는 패키지 관리자로 추가하세요:

44 44 

45**Python (uv)**45> [tab] Python (uv)

46 46>

47```bash theme={null}47> ```bash theme={null}

48uv add httpx48> uv add httpx

49```49> ```

50 

51**Python (pip)**

52 50 

53```bash theme={null}51> [tab] Python (pip)

54pip install httpx52>

55```53> ```bash theme={null}

54> pip install httpx

55> ```

56 56 

57### 날씨 도구 예제57### 날씨 도구 예제

58 58 

198 198 

199이 스니펫을 [날씨 도구 예제](#weather-tool-example)의 도구 및 서버 정의와 함께 `weather.py` 또는 `weather.ts` 한 파일에 결합한 후 터미널에서 실행합니다:199이 스니펫을 [날씨 도구 예제](#weather-tool-example)의 도구 및 서버 정의와 함께 `weather.py` 또는 `weather.ts` 한 파일에 결합한 후 터미널에서 실행합니다:

200 200 

201**TypeScript**201> [tab] TypeScript

202 202>

203```bash theme={null}203> ```bash theme={null}

204npx tsx weather.ts204> npx tsx weather.ts

205```205> ```

206 

207**Python (uv)**

208 

209```bash theme={null}

210uv run weather.py

211```

212 

213**Python (pip)**

214 206 

215SDK를 설치한 가상 환경을 활성화한 후 다음을 실행합니다:207> [tab] Python (uv)

208>

209> ```bash theme={null}

210> uv run weather.py

211> ```

216 212 

217```bash theme={null}213> [tab] Python (pip)

218python weather.py214>

219```215> SDK를 설치한 가상 환경을 활성화한 후 다음을 실행합니다:

216>

217> ```bash theme={null}

218> python weather.py

219> ```

220 220 

221Claude는 `get_temperature`를 호출하고 스크립트는 샌프란시스코의 현재 온도를 포함한 한 줄 답변을 출력합니다.221Claude는 `get_temperature`를 호출하고 스크립트는 샌프란시스코의 현재 온도를 포함한 한 줄 답변을 출력합니다.

222 222 

585>585>

586> 스크립트를 실행하기 전에 IDE 또는 편집기에서 유틸리티 파일(`utils.py` 또는 `utils.ts`)을 엽니다. 에이전트가 문서 주석을 추가할 때 파일이 실시간으로 업데이트되는 것을 볼 수 있으며, 되돌리기를 선택하면 원본으로 되돌아갑니다.586> 스크립트를 실행하기 전에 IDE 또는 편집기에서 유틸리티 파일(`utils.py` 또는 `utils.ts`)을 엽니다. 에이전트가 문서 주석을 추가할 때 파일이 실시간으로 업데이트되는 것을 볼 수 있으며, 되돌리기를 선택하면 원본으로 되돌아갑니다.

587 587 

588**Python**588> [tab] Python

589 589>

590```bash theme={null}590> ```bash theme={null}

591python try_checkpointing.py591> python try_checkpointing.py

592```592> ```

593 

594**TypeScript**

595 593 

596```bash theme={null}594> [tab] TypeScript

597npx tsx try_checkpointing.ts595>

598```596> ```bash theme={null}

597> npx tsx try_checkpointing.ts

598> ```

599 599 

600에이전트가 문서 주석을 추가한 다음 되돌리고 싶은지 묻는 프롬프트가 표시됩니다. 예를 선택하면 파일이 원본 상태로 복원됩니다.600에이전트가 문서 주석을 추가한 다음 되돌리고 싶은지 묻는 프롬프트가 표시됩니다. 예를 선택하면 파일이 원본 상태로 복원됩니다.

601 601 

386 386 

387`env` 필드를 사용하여 API 키, 토큰 및 기타 자격 증명을 MCP 서버에 전달합니다:387`env` 필드를 사용하여 API 키, 토큰 및 기타 자격 증명을 MCP 서버에 전달합니다:

388 388 

389**코드에서**389> [tab] 코드에서

390 390>

391```typescript TypeScript hidelines={1,-1} theme={null}391> ```typescript TypeScript hidelines={1,-1} theme={null}

392const _ = {392> const _ = {

393 options: {393> options: {

394 mcpServers: {394> mcpServers: {

395 "api-server": {395> "api-server": {

396 command: "npx",396> command: "npx",

397 args: ["-y", "@your-org/api-mcp-server"],397> args: ["-y", "@your-org/api-mcp-server"],

398 env: {398> env: {

399 API_KEY: process.env.API_KEY399> API_KEY: process.env.API_KEY

400 }400> }

401 }401> }

402 },402> },

403 allowedTools: ["mcp__api-server__*"]403> allowedTools: ["mcp__api-server__*"]

404 }404> }

405};405> };

406```406> ```

407 407>

408```python Python theme={null}408> ```python Python theme={null}

409options = ClaudeAgentOptions(409> options = ClaudeAgentOptions(

410 mcp_servers={410> mcp_servers={

411 "api-server": {411> "api-server": {

412 "command": "npx",412> "command": "npx",

413 "args": ["-y", "@your-org/api-mcp-server"],413> "args": ["-y", "@your-org/api-mcp-server"],

414 "env": {"API_KEY": os.environ["API_KEY"]},414> "env": {"API_KEY": os.environ["API_KEY"]},

415 }415> }

416 },416> },

417 allowed_tools=["mcp__api-server__*"],417> allowed_tools=["mcp__api-server__*"],

418)418> )

419```419> ```

420 420 

421**.mcp.json**421> [tab] .mcp.json

422 422>

423```json theme={null}423> ```json theme={null}

424{424> {

425 "mcpServers": {425> "mcpServers": {

426 "api-server": {426> "api-server": {

427 "command": "npx",427> "command": "npx",

428 "args": ["-y", "@your-org/api-mcp-server"],428> "args": ["-y", "@your-org/api-mcp-server"],

429 "env": {429> "env": {

430 "API_KEY": "${API_KEY}"430> "API_KEY": "${API_KEY}"

431 }431> }

432 }432> }

433 }433> }

434}434> }

435```435> ```

436 436>

437`${API_KEY}` 구문은 런타임에 환경 변수를 확장합니다.437> `${API_KEY}` 구문은 런타임에 환경 변수를 확장합니다.

438 438 

439### 원격 서버용 HTTP 헤더439### 원격 서버용 HTTP 헤더

440 440 

441HTTP 및 SSE 서버의 경우 서버 구성에서 직접 인증 헤더를 전달합니다:441HTTP 및 SSE 서버의 경우 서버 구성에서 직접 인증 헤더를 전달합니다:

442 442 

443**코드에서**443> [tab] 코드에서

444 444>

445```typescript TypeScript hidelines={1,-1} theme={null}445> ```typescript TypeScript hidelines={1,-1} theme={null}

446const _ = {446> const _ = {

447 options: {447> options: {

448 mcpServers: {448> mcpServers: {

449 "secure-api": {449> "secure-api": {

450 type: "http",450> type: "http",

451 url: "https://api.example.com/mcp",451> url: "https://api.example.com/mcp",

452 headers: {452> headers: {

453 Authorization: `Bearer ${process.env.API_TOKEN}`453> Authorization: `Bearer ${process.env.API_TOKEN}`

454 }454> }

455 }455> }

456 },456> },

457 allowedTools: ["mcp__secure-api__*"]457> allowedTools: ["mcp__secure-api__*"]

458 }458> }

459};459> };

460```460> ```

461 461>

462```python Python theme={null}462> ```python Python theme={null}

463options = ClaudeAgentOptions(463> options = ClaudeAgentOptions(

464 mcp_servers={464> mcp_servers={

465 "secure-api": {465> "secure-api": {

466 "type": "http",466> "type": "http",

467 "url": "https://api.example.com/mcp",467> "url": "https://api.example.com/mcp",

468 "headers": {"Authorization": f"Bearer {os.environ['API_TOKEN']}"},468> "headers": {"Authorization": f"Bearer {os.environ['API_TOKEN']}"},

469 }469> }

470 },470> },

471 allowed_tools=["mcp__secure-api__*"],471> allowed_tools=["mcp__secure-api__*"],

472)472> )

473```473> ```

474 474 

475**.mcp.json**475> [tab] .mcp.json

476 476>

477```json theme={null}477> ```json theme={null}

478{478> {

479 "mcpServers": {479> "mcpServers": {

480 "secure-api": {480> "secure-api": {

481 "type": "http",481> "type": "http",

482 "url": "https://api.example.com/mcp",482> "url": "https://api.example.com/mcp",

483 "headers": {483> "headers": {

484 "Authorization": "Bearer ${API_TOKEN}"484> "Authorization": "Bearer ${API_TOKEN}"

485 }485> }

486 }486> }

487 }487> }

488}488> }

489```489> ```

490 490>

491`${API_TOKEN}` 구문은 런타임에 환경 변수를 확장합니다.491> `${API_TOKEN}` 구문은 런타임에 환경 변수를 확장합니다.

492 492 

493헤더로 인증된 원격 서버의 완전한 작동 예제는 [저장소에서 이슈 나열](#list-issues-from-a-repository)을 참조하십시오.493헤더로 인증된 원격 서버의 완전한 작동 예제는 [저장소에서 이슈 나열](#list-issues-from-a-repository)을 참조하십시오.

494 494 

163 163 

164쿼리를 시작할 때 권한 모드를 한 번 설정하거나, 세션이 활성 상태인 동안 동적으로 변경할 수 있습니다.164쿼리를 시작할 때 권한 모드를 한 번 설정하거나, 세션이 활성 상태인 동안 동적으로 변경할 수 있습니다.

165 165 

166**쿼리 시점**166> [tab] 쿼리 시점

167 167>

168쿼리를 생성할 때 `permission_mode`(Python) 또는 `permissionMode`(TypeScript)를 전달합니다.168> 쿼리를 생성할 때 `permission_mode`(Python) 또는 `permissionMode`(TypeScript)를 전달합니다.

169 169>

170```python Python theme={null}170> ```python Python theme={null}

171import asyncio171> import asyncio

172from claude_agent_sdk import query, ClaudeAgentOptions172> from claude_agent_sdk import query, ClaudeAgentOptions

173 173>

174 174>

175async def main():175> async def main():

176 async for message in query(176> async for message in query(

177 prompt="Help me refactor this code",177> prompt="Help me refactor this code",

178 options=ClaudeAgentOptions(178> options=ClaudeAgentOptions(

179 permission_mode="default", # Set the mode here179> permission_mode="default", # Set the mode here

180 ),180> ),

181 ):181> ):

182 if hasattr(message, "result"):182> if hasattr(message, "result"):

183 print(message.result)183> print(message.result)

184 184>

185 185>

186asyncio.run(main())186> asyncio.run(main())

187```187> ```

188 188>

189```typescript TypeScript theme={null}189> ```typescript TypeScript theme={null}

190import { query } from "@anthropic-ai/claude-agent-sdk";190> import { query } from "@anthropic-ai/claude-agent-sdk";

191 191>

192async function main() {192> async function main() {

193 for await (const message of query({193> for await (const message of query({

194 prompt: "Help me refactor this code",194> prompt: "Help me refactor this code",

195 options: {195> options: {

196 permissionMode: "default" // Set the mode here196> permissionMode: "default" // Set the mode here

197 }197> }

198 })) {198> })) {

199 if ("result" in message) {199> if ("result" in message) {

200 console.log(message.result);200> console.log(message.result);

201 }201> }

202 }202> }

203}203> }

204 204>

205main();205> main();

206```206> ```

207 

208**스트리밍 중**

209 

210세션 중간에 모드를 변경하려면 `set_permission_mode()`(Python) 또는 `setPermissionMode()`(TypeScript)를 호출합니다. 새 모드는 이후의 모든 도구 요청에 즉시 적용됩니다. 이를 통해 제한적으로 시작한 후 신뢰가 쌓이면 권한을 완화할 수 있습니다. 예를 들어 Claude의 초기 접근 방식을 검토한 후 `acceptEdits`로 전환할 수 있습니다.

211 

212```python Python theme={null}

213import asyncio

214from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

215 

216 

217async def main():

218 async with ClaudeSDKClient(

219 options=ClaudeAgentOptions(

220 permission_mode="default", # Start in default mode

221 )

222 ) as client:

223 await client.query("Help me refactor this code")

224 

225 # Change mode dynamically mid-session

226 await client.set_permission_mode("acceptEdits")

227 

228 # Process messages with the new permission mode

229 async for message in client.receive_response():

230 if hasattr(message, "result"):

231 print(message.result)

232 

233 

234asyncio.run(main())

235```

236 207 

237```typescript TypeScript theme={null}208> [tab] 스트리밍 중

238import { query } from "@anthropic-ai/claude-agent-sdk";209>

239 210> 세션 중간에 모드를 변경하려면 `set_permission_mode()`(Python) 또는 `setPermissionMode()`(TypeScript)를 호출합니다. 새 모드는 이후의 모든 도구 요청에 즉시 적용됩니다. 이를 통해 제한적으로 시작한 후 신뢰가 쌓이면 권한을 완화할 수 있습니다. 예를 들어 Claude의 초기 접근 방식을 검토한 후 `acceptEdits`로 전환할 수 있습니다.

240async function main() {211>

241 const q = query({212> ```python Python theme={null}

242 prompt: "Help me refactor this code",213> import asyncio

243 options: {214> from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

244 permissionMode: "default" // Start in default mode215>

245 }216>

246 });217> async def main():

247 218> async with ClaudeSDKClient(

248 // Change mode dynamically mid-session219> options=ClaudeAgentOptions(

249 await q.setPermissionMode("acceptEdits");220> permission_mode="default", # Start in default mode

250 221> )

251 // Process messages with the new permission mode222> ) as client:

252 for await (const message of q) {223> await client.query("Help me refactor this code")

253 if ("result" in message) {224>

254 console.log(message.result);225> # Change mode dynamically mid-session

255 }226> await client.set_permission_mode("acceptEdits")

256 }227>

257}228> # Process messages with the new permission mode

258 229> async for message in client.receive_response():

259main();230> if hasattr(message, "result"):

260```231> print(message.result)

232>

233>

234> asyncio.run(main())

235> ```

236>

237> ```typescript TypeScript theme={null}

238> import { query } from "@anthropic-ai/claude-agent-sdk";

239>

240> async function main() {

241> const q = query({

242> prompt: "Help me refactor this code",

243> options: {

244> permissionMode: "default" // Start in default mode

245> }

246> });

247>

248> // Change mode dynamically mid-session

249> await q.setPermissionMode("acceptEdits");

250>

251> // Process messages with the new permission mode

252> for await (const message of q) {

253> if ("result" in message) {

254> console.log(message.result);

255> }

256> }

257> }

258>

259> main();

260> ```

261 261 

262### 모드 세부 정보262### 모드 세부 정보

263 263 

36 36 

37언어에 맞는 Agent SDK 패키지를 설치합니다:37언어에 맞는 Agent SDK 패키지를 설치합니다:

38 38 

39**TypeScript (새 프로젝트)**39> [tab] TypeScript (새 프로젝트)

40 40>

41```bash theme={null}41> ```bash theme={null}

42npm init -y42> npm init -y

43npm pkg set type=module43> npm pkg set type=module

44npm install @anthropic-ai/claude-agent-sdk44> npm install @anthropic-ai/claude-agent-sdk

45npm install --save-dev tsx45> npm install --save-dev tsx

46```46> ```

47 47>

48`package.json`에서 `"type": "module"`을 설정하면 에이전트 스크립트가 최상위 `await`를 사용할 수 있으며, [tsx](https://tsx.hirok.io)는 TypeScript 파일을 직접 실행합니다. npm은 설치가 성공하면 `added N packages`를 출력합니다.48> `package.json`에서 `"type": "module"`을 설정하면 에이전트 스크립트가 최상위 `await`를 사용할 수 있으며, [tsx](https://tsx.hirok.io)는 TypeScript 파일을 직접 실행합니다. npm은 설치가 성공하면 `added N packages`를 출력합니다.

49 

50**TypeScript (기존 프로젝트)**

51 

52```bash theme={null}

53npm install @anthropic-ai/claude-agent-sdk

54npm install --save-dev tsx

55```

56 

57[tsx](https://tsx.hirok.io)는 TypeScript 파일을 직접 실행합니다. 프로젝트가 CommonJS를 사용하는 경우 에이전트 스크립트의 이름을 `agent.ts` 대신 `agent.mts`로 지정합니다. `.mts` 확장자는 tsx가 파일을 ES 모듈로 처리하도록 하므로 전체 프로젝트를 ES 모듈로 변환하지 않고도 최상위 `await`가 작동합니다. 이 빠른 시작의 나중에 생성 및 실행 단계에서 `agent.ts` 대신 `agent.mts`를 사용합니다.

58 

59**Python (uv)**

60 

61[uv 설치](https://docs.astral.sh/uv/), 가상 환경을 자동으로 처리하는 빠른 Python 패키지 관리자입니다. 그런 다음 프로젝트를 초기화하고 SDK를 추가합니다:

62 

63```bash theme={null}

64uv init

65uv add claude-agent-sdk

66```

67 

68**Python (pip)**

69 

70가상 환경을 생성하고 활성화한 다음 패키지를 설치합니다.

71 

72macOS 또는 Linux에서:

73 

74```bash theme={null}

75python3 -m venv .venv

76source .venv/bin/activate

77pip install claude-agent-sdk

78```

79 49 

80Windows에서:50> [tab] TypeScript (기존 프로젝트)

51>

52> ```bash theme={null}

53> npm install @anthropic-ai/claude-agent-sdk

54> npm install --save-dev tsx

55> ```

56>

57> [tsx](https://tsx.hirok.io)는 TypeScript 파일을 직접 실행합니다. 프로젝트가 CommonJS를 사용하는 경우 에이전트 스크립트의 이름을 `agent.ts` 대신 `agent.mts`로 지정합니다. `.mts` 확장자는 tsx가 파일을 ES 모듈로 처리하도록 하므로 전체 프로젝트를 ES 모듈로 변환하지 않고도 최상위 `await`가 작동합니다. 이 빠른 시작의 나중에 생성 및 실행 단계에서 `agent.ts` 대신 `agent.mts`를 사용합니다.

81 58 

82```powershell theme={null}59> [tab] Python (uv)

83py -m venv .venv60>

84.venv\Scripts\Activate.ps161> [uv 설치](https://docs.astral.sh/uv/), 가상 환경을 자동으로 처리하는 빠른 Python 패키지 관리자입니다. 그런 다음 프로젝트를 초기화하고 SDK를 추가합니다:

85pip install claude-agent-sdk62>

86```63> ```bash theme={null}

64> uv init

65> uv add claude-agent-sdk

66> ```

87 67 

88PowerShell이 실행 정책 오류로 `Activate.ps1`을 차단하는 경우 먼저 `Set-ExecutionPolicy -Scope Process RemoteSigned`를 실행합니다.68> [tab] Python (pip)

69>

70> 가상 환경을 생성하고 활성화한 다음 패키지를 설치합니다.

71>

72> macOS 또는 Linux에서:

73>

74> ```bash theme={null}

75> python3 -m venv .venv

76> source .venv/bin/activate

77> pip install claude-agent-sdk

78> ```

79>

80> Windows에서:

81>

82> ```powershell theme={null}

83> py -m venv .venv

84> .venv\Scripts\Activate.ps1

85> pip install claude-agent-sdk

86> ```

87>

88> PowerShell이 실행 정책 오류로 `Activate.ps1`을 차단하는 경우 먼저 `Set-ExecutionPolicy -Scope Process RemoteSigned`를 실행합니다.

89 89 

90> [!NOTE]90> [!NOTE]

91>91>

98 98 

99[Claude 콘솔](https://platform.claude.com/)에서 API 키를 가져온 다음 에이전트를 실행할 셸에서 환경 변수로 설정합니다:99[Claude 콘솔](https://platform.claude.com/)에서 API 키를 가져온 다음 에이전트를 실행할 셸에서 환경 변수로 설정합니다:

100 100 

101**macOS / Linux**101> [tab] macOS / Linux

102 102>

103```bash theme={null}103> ```bash theme={null}

104export ANTHROPIC_API_KEY=your-api-key104> export ANTHROPIC_API_KEY=your-api-key

105```105> ```

106 

107**Windows (PowerShell)**

108 106 

109```powershell theme={null}107> [tab] Windows (PowerShell)

110$env:ANTHROPIC_API_KEY = "your-api-key"108>

111```109> ```powershell theme={null}

110> $env:ANTHROPIC_API_KEY = "your-api-key"

111> ```

112 112 

113SDK는 에이전트를 실행하는 프로세스의 환경에서 키를 읽습니다. `.env` 파일을 자동으로 로드하지 않습니다. 키를 `.env` 파일에 보관하는 경우 SDK를 호출하기 전에 `dotenv` 패키지 등으로 직접 로드합니다.113SDK는 에이전트를 실행하는 프로세스의 환경에서 키를 읽습니다. `.env` 파일을 자동으로 로드하지 않습니다. 키를 `.env` 파일에 보관하는 경우 SDK를 호출하기 전에 `dotenv` 패키지 등으로 직접 로드합니다.

114 114 

224 224 

225에이전트가 준비되었습니다. 다음 명령으로 실행합니다:225에이전트가 준비되었습니다. 다음 명령으로 실행합니다:

226 226 

227**TypeScript**227> [tab] TypeScript

228 228>

229```bash theme={null}229> ```bash theme={null}

230npx tsx agent.ts230> npx tsx agent.ts

231```231> ```

232 232>

233스크립트 이름을 `agent.mts`로 지정한 경우 `npx tsx agent.mts`를 대신 실행합니다.233> 스크립트 이름을 `agent.mts`로 지정한 경우 `npx tsx agent.mts`를 대신 실행합니다.

234 

235**Python (uv)**

236 

237```bash theme={null}

238uv run agent.py

239```

240 

241**Python (pip)**

242 234 

243가상 환경이 여전히 활성화된 상태에서:235> [tab] Python (uv)

236>

237> ```bash theme={null}

238> uv run agent.py

239> ```

244 240 

245```bash theme={null}241> [tab] Python (pip)

246python agent.py242>

247```243> 가상 환경이 여전히 활성화된 상태에서:

244>

245> ```bash theme={null}

246> python agent.py

247> ```

248 248 

249작업하는 동안 에이전트는 자신의 추론과 호출하는 각 도구를 출력하며, `Done: success`로 끝납니다. 실행 후 `utils.py`를 확인합니다. 빈 목록과 null 사용자를 처리하는 방어 코드가 표시됩니다. 에이전트는 자율적으로:249작업하는 동안 에이전트는 자신의 추론과 호출하는 각 도구를 출력하며, `Done: success`로 끝납니다. 실행 후 `utils.py`를 확인합니다. 빈 목록과 null 사용자를 처리하는 방어 코드가 표시됩니다. 에이전트는 자율적으로:

250 250 

470 470 

471각 SDK는 거부를 다르게 표시합니다:471각 SDK는 거부를 다르게 표시합니다:

472 472 

473**TypeScript**473> [tab] TypeScript

474 474>

475TypeScript SDK는 항목이 위반한 규칙을 명시하는 `Error`를 발생시킵니다. 예를 들어 `skills: ["docs:*"]`는 다음을 발생시킵니다:475> TypeScript SDK는 항목이 위반한 규칙을 명시하는 `Error`를 발생시킵니다. 예를 들어 `skills: ["docs:*"]`는 다음을 발생시킵니다:

476 476>

477```text theme={null}477> ```text theme={null}

478Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name.478> Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name.

479```479> ```

480 480>

481빈 이름은 `Skill names must be non-empty strings.`를 보고합니다.481> 빈 이름은 `Skill names must be non-empty strings.`를 보고합니다.

482 482>

483TypeScript Agent SDK 0.3.221 이전에는 SDK가 이 검사를 실행하지 않았습니다.483> TypeScript Agent SDK 0.3.221 이전에는 SDK가 이 검사를 실행하지 않았습니다.

484 

485**Python**

486 

487Python SDK는 항목이 위반한 규칙을 명시하는 `ValueError`를 발생시킵니다. 예를 들어 `skills=["docs:*"]`는 다음을 발생시킵니다:

488 

489```text theme={null}

490ValueError: Invalid skill name 'docs:*': wildcard-suffix names are not allowed; list each skill by its exact name.

491```

492 

493빈 이름은 `Skill names must be non-empty strings`를 보고합니다.

494 484 

495Python Agent SDK 0.2.129 이전에는 SDK가 이 검사를 실행하지 않았습니다.485> [tab] Python

486>

487> Python SDK는 항목이 위반한 규칙을 명시하는 `ValueError`를 발생시킵니다. 예를 들어 `skills=["docs:*"]`는 다음을 발생시킵니다:

488>

489> ```text theme={null}

490> ValueError: Invalid skill name 'docs:*': wildcard-suffix names are not allowed; list each skill by its exact name.

491> ```

492>

493> 빈 이름은 `Skill names must be non-empty strings`를 보고합니다.

494>

495> Python Agent SDK 0.2.129 이전에는 SDK가 이 검사를 실행하지 않았습니다.

496 496 

497### 추가 문제 해결497### 추가 문제 해결

498 498 

16 16 

17에이전트가 웹을 검색하고 레시피를 가져오는 레시피 앱을 생각해 봅시다. 구조화된 출력이 없으면 직접 파싱해야 하는 자유 형식 텍스트를 얻습니다. 구조화된 출력을 사용하면 원하는 형태를 정의하고 앱에서 직접 사용할 수 있는 타입이 지정된 데이터를 얻습니다.17에이전트가 웹을 검색하고 레시피를 가져오는 레시피 앱을 생각해 봅시다. 구조화된 출력이 없으면 직접 파싱해야 하는 자유 형식 텍스트를 얻습니다. 구조화된 출력을 사용하면 원하는 형태를 정의하고 앱에서 직접 사용할 수 있는 타입이 지정된 데이터를 얻습니다.

18 18 

19> **구조화된 출력 없음**19> [accordion] 구조화된 출력 없음

20>20>

21> ```text theme={null}21> ```text theme={null}

22> 여기 클래식 초콜릿 칩 쿠키 레시피입니다!22> 여기 클래식 초콜릿 칩 쿠키 레시피입니다!

32>32>

33> 이를 앱에서 사용하려면 제목을 파싱하고, "15분"을 숫자로 변환하고, 재료와 지시사항을 분리하고, 응답 전체에서 일관되지 않은 형식을 처리해야 합니다.33> 이를 앱에서 사용하려면 제목을 파싱하고, "15분"을 숫자로 변환하고, 재료와 지시사항을 분리하고, 응답 전체에서 일관되지 않은 형식을 처리해야 합니다.

34 34 

35> **구조화된 출력 포함**35> [accordion] 구조화된 출력 포함

36>36>

37> ```jsonc theme={null}37> ```jsonc theme={null}

38> {38> {

225 225 

226다음 스니펫의 `ask_user` 및 `askUser` 헬퍼는 애플리케이션의 자체 프롬프트 UI를 나타냅니다.226다음 스니펫의 `ask_user` 및 `askUser` 헬퍼는 애플리케이션의 자체 프롬프트 UI를 나타냅니다.

227 227 

228**승인**228> [tab] 승인

229 229>

230사용자가 작업을 그대로 승인합니다. 콜백에서 `input`을 변경하지 않고 전달하면 도구가 Claude가 요청한 대로 정확히 실행됩니다.230> 사용자가 작업을 그대로 승인합니다. 콜백에서 `input`을 변경하지 않고 전달하면 도구가 Claude가 요청한 대로 정확히 실행됩니다.

231 231>

232```python Python theme={null}232> ```python Python theme={null}

233async def can_use_tool(tool_name, input_data, context):233> async def can_use_tool(tool_name, input_data, context):

234 print(f"Claude wants to use {tool_name}")234> print(f"Claude wants to use {tool_name}")

235 approved = await ask_user("Allow this action?")235> approved = await ask_user("Allow this action?")

236 236>

237 if approved:237> if approved:

238 return PermissionResultAllow(updated_input=input_data)238> return PermissionResultAllow(updated_input=input_data)

239 return PermissionResultDeny(message="User declined")239> return PermissionResultDeny(message="User declined")

240```240> ```

241 241>

242```typescript TypeScript theme={null}242> ```typescript TypeScript theme={null}

243canUseTool: async (toolName, input) => {243> canUseTool: async (toolName, input) => {

244 console.log(`Claude wants to use ${toolName}`);244> console.log(`Claude wants to use ${toolName}`);

245 const approved = await askUser("Allow this action?");245> const approved = await askUser("Allow this action?");

246 246>

247 if (approved) {247> if (approved) {

248 return { behavior: "allow", updatedInput: input };248> return { behavior: "allow", updatedInput: input };

249 }249> }

250 return { behavior: "deny", message: "User declined" };250> return { behavior: "deny", message: "User declined" };

251};251> };

252```252> ```

253 253 

254**변경 사항과 함께 승인**254> [tab] 변경 사항과 함께 승인

255 255>

256사용자가 승인하지만 먼저 요청을 수정하려고 합니다. 도구가 실행되기 전에 입력을 변경할 수 있습니다. Claude는 결과를 보지만 변경 사항을 알려주지 않습니다. 매개변수 정제, 제약 조건 추가 또는 액세스 범위 지정에 유용합니다.256> 사용자가 승인하지만 먼저 요청을 수정하려고 합니다. 도구가 실행되기 전에 입력을 변경할 수 있습니다. Claude는 결과를 보지만 변경 사항을 알려주지 않습니다. 매개변수 정제, 제약 조건 추가 또는 액세스 범위 지정에 유용합니다.

257 257>

258```python Python theme={null}258> ```python Python theme={null}

259async def can_use_tool(tool_name, input_data, context):259> async def can_use_tool(tool_name, input_data, context):

260 if tool_name == "Bash":260> if tool_name == "Bash":

261 # 사용자가 승인했지만 모든 명령을 샌드박스로 범위 지정261> # 사용자가 승인했지만 모든 명령을 샌드박스로 범위 지정

262 sandboxed_input = {**input_data}262> sandboxed_input = {**input_data}

263 sandboxed_input["command"] = input_data["command"].replace(263> sandboxed_input["command"] = input_data["command"].replace(

264 "/tmp", "/tmp/sandbox"264> "/tmp", "/tmp/sandbox"

265 )265> )

266 return PermissionResultAllow(updated_input=sandboxed_input)266> return PermissionResultAllow(updated_input=sandboxed_input)

267 return PermissionResultAllow(updated_input=input_data)267> return PermissionResultAllow(updated_input=input_data)

268```268> ```

269 269>

270```typescript TypeScript theme={null}270> ```typescript TypeScript theme={null}

271canUseTool: async (toolName, input) => {271> canUseTool: async (toolName, input) => {

272 if (toolName === "Bash") {272> if (toolName === "Bash") {

273 // 사용자가 승인했지만 모든 명령을 샌드박스로 범위 지정273> // 사용자가 승인했지만 모든 명령을 샌드박스로 범위 지정

274 const sandboxedInput = {274> const sandboxedInput = {

275 ...input,275> ...input,

276 command: input.command.replace("/tmp", "/tmp/sandbox")276> command: input.command.replace("/tmp", "/tmp/sandbox")

277 };277> };

278 return { behavior: "allow", updatedInput: sandboxedInput };278> return { behavior: "allow", updatedInput: sandboxedInput };

279 }279> }

280 return { behavior: "allow", updatedInput: input };280> return { behavior: "allow", updatedInput: input };

281};281> };

282```282> ```

283 283 

284**승인 및 기억**284> [tab] 승인 및 기억

285 285>

286사용자가 승인하고 이런 종류의 호출에 대해 다시 묻지 않기를 원합니다. 세 번째 콜백 인수는 `suggestions`을 포함하며, 이는 준비된 [`PermissionUpdate`](https://code.claude.com/docs/ko/agent-sdk/typescript#permissionupdate) 항목의 배열입니다. `updatedPermissions`에서 하나를 다시 에코하여 적용합니다. `localSettings` 대상이 있는 제안은 규칙을 `.claude/settings.local.json`에 작성하므로 향후 세션에서 일치하는 호출에 대한 프롬프트를 건너뜁니다.286> 사용자가 승인하고 이런 종류의 호출에 대해 다시 묻지 않기를 원합니다. 세 번째 콜백 인수는 `suggestions`을 포함하며, 이는 준비된 [`PermissionUpdate`](https://code.claude.com/docs/ko/agent-sdk/typescript#permissionupdate) 항목의 배열입니다. `updatedPermissions`에서 하나를 다시 에코하여 적용합니다. `localSettings` 대상이 있는 제안은 규칙을 `.claude/settings.local.json`에 작성하므로 향후 세션에서 일치하는 호출에 대한 프롬프트를 건너뜁니다.

287 287>

288TypeScript에서는 옵션이 [`suppressAlwaysAllowRule: true`](https://code.claude.com/docs/ko/agent-sdk/typescript#canusetool)를 포함하는 요청에 대해 항상 허용 선택을 건너뜁니다. 힌트는 Agent SDK v0.3.268 이상이 필요하며, Python `context`는 이를 포함하지 않습니다.288> TypeScript에서는 옵션이 [`suppressAlwaysAllowRule: true`](https://code.claude.com/docs/ko/agent-sdk/typescript#canusetool)를 포함하는 요청에 대해 항상 허용 선택을 건너뜁니다. 힌트는 Agent SDK v0.3.268 이상이 필요하며, Python `context`는 이를 포함하지 않습니다.

289 289>

290Python 예제는 `claude-agent-sdk` 0.1.80 이상이 필요합니다.290> Python 예제는 `claude-agent-sdk` 0.1.80 이상이 필요합니다.

291 291>

292```python Python theme={null}292> ```python Python theme={null}

293async def can_use_tool(tool_name, input_data, context):293> async def can_use_tool(tool_name, input_data, context):

294 choice = await ask_user(f"Allow {tool_name}?", ["once", "always", "no"])294> choice = await ask_user(f"Allow {tool_name}?", ["once", "always", "no"])

295 295>

296 if choice == "always":296> if choice == "always":

297 persist = [297> persist = [

298 s for s in context.suggestions if s.destination == "localSettings"298> s for s in context.suggestions if s.destination == "localSettings"

299 ]299> ]

300 return PermissionResultAllow(300> return PermissionResultAllow(

301 updated_input=input_data, updated_permissions=persist301> updated_input=input_data, updated_permissions=persist

302 )302> )

303 if choice == "once":303> if choice == "once":

304 return PermissionResultAllow(updated_input=input_data)304> return PermissionResultAllow(updated_input=input_data)

305 return PermissionResultDeny(message="User declined")305> return PermissionResultDeny(message="User declined")

306```306> ```

307 307>

308```typescript TypeScript theme={null}308> ```typescript TypeScript theme={null}

309canUseTool: async (toolName, input, { suggestions = [] }) => {309> canUseTool: async (toolName, input, { suggestions = [] }) => {

310 const choice = await askUser(`Allow ${toolName}?`, ["once", "always", "no"]);310> const choice = await askUser(`Allow ${toolName}?`, ["once", "always", "no"]);

311 311>

312 if (choice === "always") {312> if (choice === "always") {

313 const persist = suggestions.filter(313> const persist = suggestions.filter(

314 (s) => s.destination === "localSettings"314> (s) => s.destination === "localSettings"

315 );315> );

316 return {316> return {

317 behavior: "allow",317> behavior: "allow",

318 updatedInput: input,318> updatedInput: input,

319 updatedPermissions: persist319> updatedPermissions: persist

320 };320> };

321 }321> }

322 if (choice === "once") {322> if (choice === "once") {

323 return { behavior: "allow", updatedInput: input };323> return { behavior: "allow", updatedInput: input };

324 }324> }

325 return { behavior: "deny", message: "User declined" };325> return { behavior: "deny", message: "User declined" };

326};326> };

327```327> ```

328 328 

329**거부**329> [tab] 거부

330 330>

331사용자가 이 작업이 발생하기를 원하지 않습니다. 도구를 차단하고 이유를 설명하는 메시지를 제공합니다. Claude는 이 메시지를 보고 다른 접근 방식을 시도할 수 있습니다.331> 사용자가 이 작업이 발생하기를 원하지 않습니다. 도구를 차단하고 이유를 설명하는 메시지를 제공합니다. Claude는 이 메시지를 보고 다른 접근 방식을 시도할 수 있습니다.

332 332>

333```python Python theme={null}333> ```python Python theme={null}

334async def can_use_tool(tool_name, input_data, context):334> async def can_use_tool(tool_name, input_data, context):

335 approved = await ask_user(f"Allow {tool_name}?")335> approved = await ask_user(f"Allow {tool_name}?")

336 336>

337 if not approved:337> if not approved:

338 return PermissionResultDeny(message="User rejected this action")338> return PermissionResultDeny(message="User rejected this action")

339 return PermissionResultAllow(updated_input=input_data)339> return PermissionResultAllow(updated_input=input_data)

340```340> ```

341 341>

342```typescript TypeScript theme={null}342> ```typescript TypeScript theme={null}

343canUseTool: async (toolName, input) => {343> canUseTool: async (toolName, input) => {

344 const approved = await askUser(`Allow ${toolName}?`);344> const approved = await askUser(`Allow ${toolName}?`);

345 345>

346 if (!approved) {346> if (!approved) {

347 return {347> return {

348 behavior: "deny",348> behavior: "deny",

349 message: "User rejected this action"349> message: "User rejected this action"

350 };350> };

351 }351> }

352 return { behavior: "allow", updatedInput: input };352> return { behavior: "allow", updatedInput: input };

353};353> };

354```354> ```

355 355 

356**대안 제안**356> [tab] 대안 제안

357 357>

358사용자가 이 특정 작업을 원하지 않지만 다른 아이디어가 있습니다. 도구를 차단하고 메시지에 지침을 포함합니다. Claude는 이를 읽고 피드백에 따라 진행 방법을 결정합니다.358> 사용자가 이 특정 작업을 원하지 않지만 다른 아이디어가 있습니다. 도구를 차단하고 메시지에 지침을 포함합니다. Claude는 이를 읽고 피드백에 따라 진행 방법을 결정합니다.

359 359>

360```python Python theme={null}360> ```python Python theme={null}

361async def can_use_tool(tool_name, input_data, context):361> async def can_use_tool(tool_name, input_data, context):

362 if tool_name == "Bash" and "rm" in input_data.get("command", ""):362> if tool_name == "Bash" and "rm" in input_data.get("command", ""):

363 # 사용자가 삭제를 원하지 않음, 대신 압축을 제안363> # 사용자가 삭제를 원하지 않음, 대신 압축을 제안

364 return PermissionResultDeny(364> return PermissionResultDeny(

365 message="User doesn't want to delete files. They asked if you could compress them into an archive instead."365> message="User doesn't want to delete files. They asked if you could compress them into an archive instead."

366 )366> )

367 return PermissionResultAllow(updated_input=input_data)367> return PermissionResultAllow(updated_input=input_data)

368```368> ```

369 369>

370```typescript TypeScript theme={null}370> ```typescript TypeScript theme={null}

371canUseTool: async (toolName, input) => {371> canUseTool: async (toolName, input) => {

372 if (toolName === "Bash" && input.command.includes("rm")) {372> if (toolName === "Bash" && input.command.includes("rm")) {

373 // 사용자가 삭제를 원하지 않음, 대신 압축을 제안373> // 사용자가 삭제를 원하지 않음, 대신 압축을 제안

374 return {374> return {

375 behavior: "deny",375> behavior: "deny",

376 message:376> message:

377 "User doesn't want to delete files. They asked if you could compress them into an archive instead."377> "User doesn't want to delete files. They asked if you could compress them into an archive instead."

378 };378> };

379 }379> }

380 return { behavior: "allow", updatedInput: input };380> return { behavior: "allow", updatedInput: input };

381};381> };

382```382> ```

383 383 

384**완전히 리디렉션**384> [tab] 완전히 리디렉션

385 385>

386방향의 완전한 변경(단순한 밀어붙이기가 아닌)의 경우 [스트리밍 입력](https://code.claude.com/docs/ko/agent-sdk/streaming-vs-single-mode.md)을 사용하여 Claude에 새로운 지시를 직접 보냅니다. 이는 현재 도구 요청을 우회하고 Claude에 완전히 새로운 지시를 따르도록 합니다.386> 방향의 완전한 변경(단순한 밀어붙이기가 아닌)의 경우 [스트리밍 입력](https://code.claude.com/docs/ko/agent-sdk/streaming-vs-single-mode.md)을 사용하여 Claude에 새로운 지시를 직접 보냅니다. 이는 현재 도구 요청을 우회하고 Claude에 완전히 새로운 지시를 따르도록 합니다.

387 387 

388## 명확화 질문 처리388## 명확화 질문 처리

389 389 

13| [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md) | 한 세션 내에서 자신의 컨텍스트에서 부작업을 수행하고 요약을 반환하는 위임된 작업자 | 부작업이 검색 결과, 로그 또는 다시 참조하지 않을 파일 내용으로 주 대화를 넘칠 때 |13| [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md) | 한 세션 내에서 자신의 컨텍스트에서 부작업을 수행하고 요약을 반환하는 위임된 작업자 | 부작업이 검색 결과, 로그 또는 다시 참조하지 않을 파일 내용으로 주 대화를 넘칠 때 |

14| [에이전트 뷰](https://code.claude.com/docs/ko/agent-view.md) | `claude agents`로 열 수 있는 백그라운드에서 실행 중인 세션을 디스패치하고 모니터링하는 하나의 화면. 연구 미리보기 | 여러 개의 독립적인 작업이 있고 작업을 넘기고, 상태를 한눈에 확인하고, 필요할 때만 개입하고 싶을 때 |14| [에이전트 뷰](https://code.claude.com/docs/ko/agent-view.md) | `claude agents`로 열 수 있는 백그라운드에서 실행 중인 세션을 디스패치하고 모니터링하는 하나의 화면. 연구 미리보기 | 여러 개의 독립적인 작업이 있고 작업을 넘기고, 상태를 한눈에 확인하고, 필요할 때만 개입하고 싶을 때 |

15| [에이전트 팀](https://code.claude.com/docs/ko/agent-teams.md) | 공유 작업 목록과 에이전트 간 메시징을 통해 조율되는 여러 세션으로, 리더가 관리합니다. 실험적이며 기본적으로 비활성화됨 | Claude가 프로젝트를 여러 부분으로 나누고, 할당하고, 작업자들을 동기화 상태로 유지하기를 원할 때 |15| [에이전트 팀](https://code.claude.com/docs/ko/agent-teams.md) | 공유 작업 목록과 에이전트 간 메시징을 통해 조율되는 여러 세션으로, 리더가 관리합니다. 실험적이며 기본적으로 비활성화됨 | Claude가 프로젝트를 여러 부분으로 나누고, 할당하고, 작업자들을 동기화 상태로 유지하기를 원할 때 |

16| [프로젝트](https://code.claude.com/docs/ko/claude-projects.md) | claude.ai/code 또는 데스크톱 앱에서의 지속적인 대화. Claude는 threads라고 불리는 병렬 세션을 클라우드에서 시작하거나, 사용자가 요청할 때 Remote Control을 통해 사용자의 컴퓨터에서 시작하고, 각 세션에 프로젝트의 지침을 제공하며, 어느 것이 사용자를 필요로 하는지 표시합니다. Pro 및 Max에서 공개 베타 | 작업이 여러 날 또는 주에 걸쳐 많은 작업을 포함하고, 사용자의 머신이 꺼져 있을 때도 계속 실행되어야 하며, 각 세션을 디스패치하고 추적하기보다는 한 번에 설명하고 싶을 때 |16| [프로젝트](https://code.claude.com/docs/ko/claude-projects.md) | claude.ai/code 또는 데스크톱 앱에서의 하나의 지속적인 대화. Claude는 threads라고 불리는 병렬 세션을 클라우드에서 시작하거나, 사용자가 요청할 때 Remote Control을 통해 사용자의 컴퓨터에서 시작합니다. 각 세션에 프로젝트의 지침을 제공하고, 어느 세션이 사용자를 필요로 하는지 표시합니다. Pro, Max, Ultra에서 공개 베타 | 작업이 여러 날 또는 주에 걸쳐 많은 작업을 포함하고, 사용자의 머신이 꺼져 있을 때도 계속 실행되어야 하며, 각 세션을 디스패치하고 추적하기보다는 한 번에 설명하고 싶을 때 |

17| [동적 워크플로우](https://code.claude.com/docs/ko/workflows.md) | 많은 서브에이전트를 실행하고 그 결과를 교차 검증하는 스크립트로, 한 번에 조율하기에는 너무 큰 작업용입니다. 한 번의 패스 이상이 필요한 작업용입니다 | 작업이 소수의 서브에이전트로는 조율할 수 없을 때, 또는 결과를 서로 검증하고 싶을 때: 코드베이스 전체 감사, 500개 파일 마이그레이션, 교차 검증된 연구, 또는 여러 각도에서 작성된 계획 |17| [동적 워크플로우](https://code.claude.com/docs/ko/workflows.md) | 많은 서브에이전트를 실행하고 그 결과를 교차 검증하는 스크립트로, 한 번에 조율하기에는 너무 큰 작업용입니다. 한 번의 패스 이상이 필요한 작업용입니다 | 작업이 소수의 서브에이전트로는 조율할 수 없을 때, 또는 결과를 서로 검증하고 싶을 때: 코드베이스 전체 감사, 500개 파일 마이그레이션, 교차 검증된 연구, 또는 여러 각도에서 작성된 계획 |

18 18 

19모든 접근 방식에서 작업자는 Claude 세션입니다. 다른 도구를 포함하려면 [MCP 서버](https://code.claude.com/docs/ko/mcp.md)로 Claude에 노출하세요.19모든 접근 방식에서 작업자는 Claude 세션입니다. 다른 도구를 포함하려면 [MCP 서버](https://code.claude.com/docs/ko/mcp.md)로 Claude에 노출하세요.

8 8 

9> [!NOTE]9> [!NOTE]

10>10>

11> 아티팩트는 Pro, Max, Team, Enterprise 플랜에서 사용 가능하며 [`/login`](https://code.claude.com/docs/ko/setup#authenticate)으로 로그인한 세션이 필요합니다. 전체 요구사항은 [가용성](#availability)을 참조하십시오.11> 아티팩트는 Pro, Max, Ultra, Team, Enterprise 플랜에서 사용 가능하며 [`/login`](https://code.claude.com/docs/ko/setup#authenticate)으로 로그인한 세션이 필요합니다. 전체 요구사항은 [가용성](#availability)을 참조하십시오.

12 12 

13[아티팩트](https://claude.com/features/artifacts)는 Claude Code가 세션에서 claude.ai의 비공개 URL로 게시하는 라이브 인터랙티브 웹 페이지입니다. 브라우저에서 열 수 있으며, 세션이 계속되면서 제자리에서 업데이트됩니다. 다른 사람이 보기를 원할 때 페이지 헤더에서 공유하십시오.13[아티팩트](https://claude.com/features/artifacts)는 Claude Code가 세션에서 claude.ai의 비공개 URL로 게시하는 라이브 인터랙티브 웹 페이지입니다. 브라우저에서 열 수 있으며, 세션이 계속되면서 제자리에서 업데이트됩니다. 다른 사람이 보기를 원할 때 페이지 헤더에서 공유하십시오.

14 14 

197 197 

198## MCP 커넥터로 실시간 데이터 가져오기198## MCP 커넥터로 실시간 데이터 가져오기

199 199 

200아티팩트는 누군가 이를 볼 때마다 [MCP 커넥터](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)를 호출할 수 있으므로, 페이지는 이를 구축한 세션에서 수집한 스냅샷이 아닌 현재 데이터를 표시합니다. 아티팩트의 커넥터 호출은 Pro, Max, Team, Enterprise 플랜에서 사용 가능하며 Claude Code v2.1.209 이상이 필요합니다. 이전 버전에서는 Claude가 세션이 구축하는 동안 수집한 데이터로 페이지를 게시합니다.200아티팩트는 누군가 이를 볼 때마다 [MCP 커넥터](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)를 호출할 수 있으므로, 페이지는 이를 구축한 세션에서 수집한 스냅샷이 아닌 현재 데이터를 표시합니다. 아티팩트의 커넥터 호출은 Pro, Max, Ultra, Team, Enterprise 플랜에서 사용 가능하며 Claude Code v2.1.209 이상이 필요합니다. 이전 버전에서는 Claude가 세션이 구축하는 동안 수집한 데이터로 페이지를 게시합니다.

201 201 

202커넥터 기반 페이지를 만들려면 프롬프트에서 커넥터와 원하는 데이터의 이름을 지정합니다:202커넥터 기반 페이지를 만들려면 프롬프트에서 커넥터와 원하는 데이터의 이름을 지정합니다:

203 203 

314 314 

315> [!NOTE]315> [!NOTE]

316>316>

317> 템플릿은 베타 버전입니다. Pro, Max 및 Team 플랜에서는 기본적으로 활성화되어 있습니다. Enterprise 플랜에서는 Owner가 **조직 설정 > 아티팩트** 아래에서 [각 템플릿을 활성화합니다](https://support.claude.com/en/articles/16994751-artifacts-admin-guide-for-team-and-enterprise-plans). 조직에서 Slides 템플릿이 비활성화되어 있으면 `/slides`가 나타나지 않습니다. Design 템플릿이 비활성화되어 있으면 `/design`이 디자인을 초안 작성하지 않습니다. 두 명령 모두 Claude Code v2.1.265 이상과 [아티팩트를 사용할 수 있는](#availability) 세션이 필요합니다.317> 템플릿은 베타 버전입니다. Pro, Max, Ultra 및 Team 플랜에서는 기본적으로 활성화되어 있습니다. Enterprise 플랜에서는 Owner가 **조직 설정 > 아티팩트** 아래에서 [각 템플릿을 활성화합니다](https://support.claude.com/en/articles/16994751-artifacts-admin-guide-for-team-and-enterprise-plans). 조직에서 Slides 템플릿이 비활성화되어 있으면 `/slides`가 나타나지 않습니다. Design 템플릿이 비활성화되어 있으면 `/design`이 디자인을 초안 작성하지 않습니다. 두 명령 모두 Claude Code v2.1.265 이상과 [아티팩트를 사용할 수 있는](#availability) 세션이 필요합니다.

318 318 

319### 슬라이드 덱 만들기319### 슬라이드 덱 만들기

320 320 

368 368 

369| 요구사항 | 사용 가능한 경우 |369| 요구사항 | 사용 가능한 경우 |

370| :- | :- |370| :- | :- |

371| 플랜 | Pro, Max, Team 또는 Enterprise. Pro 및 Max 플랜에서는 artifacts가 공유할 때까지 사용자에게만 비공개이며 관리자 관리가 적용되지 않습니다. Team 및 Enterprise 플랜에서는 artifacts가 기본적으로 활성화되며, Owner가 claude.ai 관리자 설정에서 [이를 조직에 대해 비활성화](#manage-artifacts-for-your-organization)할 수 있습니다. |371| 플랜 | Pro, Max, Ultra, Team 또는 Enterprise. Pro, Max 및 Ultra 플랜에서는 아티팩트가 공유할 때까지 사용자에게만 비공개이며 관리자 관리가 적용되지 않습니다. Team 및 Enterprise 플랜에서는 아티팩트가 기본적으로 활성화되며, Owner가 claude.ai 관리자 설정에서 [이를 조직에 대해 비활성화](#manage-artifacts-for-your-organization)할 수 있습니다. |

372| 인증 | 세션이 claude.ai 계정으로 지원됩니다: CLI 또는 데스크톱 앱에서 `/login`으로 로그인합니다. Claude Tag 세션은 로그인 단계가 필요하지 않습니다. API 키, [게이트웨이 토큰](https://code.claude.com/docs/ko/llm-gateway) 또는 클라우드 제공자 자격 증명을 사용하는 세션은 게시할 수 없습니다. |372| 인증 | 세션이 claude.ai 계정으로 지원됩니다: CLI 또는 데스크톱 앱에서 `/login`으로 로그인합니다. Claude Tag 세션은 로그인 단계가 필요하지 않습니다. API 키, [게이트웨이 토큰](https://code.claude.com/docs/ko/llm-gateway) 또는 클라우드 제공자 자격 증명을 사용하는 세션은 게시할 수 없습니다. |

373| 모델 제공자 | Anthropic API. [Amazon Bedrock](https://code.claude.com/docs/ko/amazon-bedrock.md), [Google Cloud의 Agent Platform](https://code.claude.com/docs/ko/google-vertex-ai.md) 또는 [Microsoft Foundry](https://code.claude.com/docs/ko/microsoft-foundry.md)에서는 사용할 수 없습니다. |373| 모델 제공자 | Anthropic API. [Amazon Bedrock](https://code.claude.com/docs/ko/amazon-bedrock.md), [Google Cloud의 Agent Platform](https://code.claude.com/docs/ko/google-vertex-ai.md) 또는 [Microsoft Foundry](https://code.claude.com/docs/ko/microsoft-foundry.md)에서는 사용할 수 없습니다. |

374| 조직 정책 | 고객 관리 암호화 키(CMEK), HIPAA 및 [Zero Data Retention](https://code.claude.com/docs/ko/zero-data-retention.md)이 조직에 대해 활성화되지 않았습니다. |374| 조직 정책 | 고객 관리 암호화 키(CMEK), HIPAA 및 [Zero Data Retention](https://code.claude.com/docs/ko/zero-data-retention.md)이 조직에 대해 활성화되지 않았습니다. |

23 23 

24다음 계정 유형 중 하나로 인증할 수 있습니다:24다음 계정 유형 중 하나로 인증할 수 있습니다:

25 25 

26* **Claude Pro 또는 Max 구독**: claude.ai 계정으로 로그인합니다. [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max)에서 구독합니다.26* **Claude Pro, Max 또는 Ultra 구독**: claude.ai 계정으로 로그인합니다. [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max)에서 구독합니다.

27* **Claude for Teams 또는 Enterprise**: 팀 관리자가 초대한 claude.ai 계정으로 로그인합니다.27* **Claude for Teams 또는 Enterprise**: 팀 관리자가 초대한 claude.ai 계정으로 로그인합니다.

28* **Claude Console**: Console 자격증명으로 로그인합니다. 관리자가 먼저 [초대](#claude-console-authentication)해야 합니다. [API 키를 생성](#sign-in-without-an-api-key)하거나 생성하지 않고 로그인할 수 있습니다.28* **Claude Console**: Console 자격증명으로 로그인합니다. 관리자가 먼저 [초대](#claude-console-authentication)해야 합니다. [API 키를 생성](#sign-in-without-an-api-key)하거나 생성하지 않고 로그인할 수 있습니다.

29* **클라우드 제공자**: 조직에서 [Amazon Bedrock](https://code.claude.com/docs/ko/amazon-bedrock.md), [Google Cloud의 Agent Platform](https://code.claude.com/docs/ko/google-vertex-ai.md), 또는 [Microsoft Foundry](https://code.claude.com/docs/ko/microsoft-foundry.md)를 사용하는 경우 `claude`를 실행하기 전에 필요한 환경 변수를 설정하거나 로그인 프롬프트에서 **3rd-party platform**을 선택합니다. 이는 Bedrock 및 Vertex AI에 대한 대화형 설정 마법사를 시작합니다. 브라우저 로그인이 필요하지 않습니다.29* **클라우드 제공자**: 조직에서 [Amazon Bedrock](https://code.claude.com/docs/ko/amazon-bedrock.md), [Google Cloud의 Agent Platform](https://code.claude.com/docs/ko/google-vertex-ai.md), 또는 [Microsoft Foundry](https://code.claude.com/docs/ko/microsoft-foundry.md)를 사용하는 경우 `claude`를 실행하기 전에 필요한 환경 변수를 설정하거나 로그인 프롬프트에서 **3rd-party platform**을 선택합니다. 이는 Bedrock 및 Vertex AI에 대한 대화형 설정 마법사를 시작합니다. 브라우저 로그인이 필요하지 않습니다.

2534. [`apiKeyHelper`](https://code.claude.com/docs/ko/settings-reference#apikeyhelper) 스크립트 출력. 자격증명 모음에서 가져온 단기 토큰과 같은 동적 또는 회전 자격증명에 사용하세요.2534. [`apiKeyHelper`](https://code.claude.com/docs/ko/settings-reference#apikeyhelper) 스크립트 출력. 자격증명 모음에서 가져온 단기 토큰과 같은 동적 또는 회전 자격증명에 사용하세요.

2545. `CLAUDE_CODE_OAUTH_TOKEN` 환경 변수. [`claude setup-token`](#generate-a-long-lived-token)으로 생성된 장기 OAuth 토큰. 브라우저 로그인을 사용할 수 없는 CI 파이프라인 및 스크립트에 사용하세요. 변수가 설정된 동안 `/login`을 실행하면, Claude Code는 현재 세션을 새 로그인으로 전환하지만, 셸 프로필이나 [설정 파일](https://code.claude.com/docs/ko/settings.md)의 `env` 블록에서 제거할 때까지 모든 새 세션에서 변수를 다시 읽습니다.2545. `CLAUDE_CODE_OAUTH_TOKEN` 환경 변수. [`claude setup-token`](#generate-a-long-lived-token)으로 생성된 장기 OAuth 토큰. 브라우저 로그인을 사용할 수 없는 CI 파이프라인 및 스크립트에 사용하세요. 변수가 설정된 동안 `/login`을 실행하면, Claude Code는 현재 세션을 새 로그인으로 전환하지만, 셸 프로필이나 [설정 파일](https://code.claude.com/docs/ko/settings.md)의 `env` 블록에서 제거할 때까지 모든 새 세션에서 변수를 다시 읽습니다.

2556. Anthropic 프로필 및 페더레이션 자격증명. `ant` CLI 및 Workload Identity Federation이 사용하는 자격증명입니다. `ant auth login`이 작성한 프로필은 `ANTHROPIC_PROFILE`에서 이름을 지정할 때만 여기에 순위가 매겨집니다. 그렇지 않으면 `/login` 아래에 순위가 매겨집니다. [Anthropic 프로필 및 페더레이션 자격증명](#anthropic-profiles-and-federation-credentials)을 참조하세요.2556. Anthropic 프로필 및 페더레이션 자격증명. `ant` CLI 및 Workload Identity Federation이 사용하는 자격증명입니다. `ant auth login`이 작성한 프로필은 `ANTHROPIC_PROFILE`에서 이름을 지정할 때만 여기에 순위가 매겨집니다. 그렇지 않으면 `/login` 아래에 순위가 매겨집니다. [Anthropic 프로필 및 페더레이션 자격증명](#anthropic-profiles-and-federation-credentials)을 참조하세요.

2567. `/login`의 구독 OAuth 자격증명. 이는 Claude Pro, Max, Team, Enterprise 사용자의 기본값입니다.2567. `/login`의 구독 OAuth 자격 증명. 이는 Claude Pro, Max, Ultra, Team, Enterprise 사용자의 기본값입니다.

257 257 

258로그인한 [Claude apps gateway](https://code.claude.com/docs/ko/claude-apps-gateway) 세션은 이 목록 외에 있습니다. Amazon Bedrock 또는 Google Cloud의 Agent Platform과 같은 공급자 선택이며, 이들을 능가합니다. 게이트웨이 세션이 있으면, `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, 또는 `CLAUDE_CODE_USE_FOUNDRY`가 설정되어 있어도 CLI는 게이트웨이 토큰으로 인증하며, 베어러 토큰, API 키, `apiKeyHelper`, 프로필과 같은 위의 자격증명 소스는 사용되지 않습니다.258로그인한 [Claude apps gateway](https://code.claude.com/docs/ko/claude-apps-gateway) 세션은 이 목록 외에 있습니다. Amazon Bedrock 또는 Google Cloud의 Agent Platform과 같은 공급자 선택이며, 이들을 능가합니다. 게이트웨이 세션이 있으면, `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, 또는 `CLAUDE_CODE_USE_FOUNDRY`가 설정되어 있어도 CLI는 게이트웨이 토큰으로 인증하며, 베어러 토큰, API 키, `apiKeyHelper`, 프로필과 같은 위의 자격증명 소스는 사용되지 않습니다.

259 259 

300 300 

301명령은 `/login`과 동일한 브라우저 인증 흐름을 열고, 브라우저에서 액세스를 승인한 후 토큰이 터미널에 출력됩니다. 토큰을 어디에도 저장하지 않습니다. 복사하여 인증하려는 곳에 `CLAUDE_CODE_OAUTH_TOKEN` 환경 변수로 설정합니다:301명령은 `/login`과 동일한 브라우저 인증 흐름을 열고, 브라우저에서 액세스를 승인한 후 토큰이 터미널에 출력됩니다. 토큰을 어디에도 저장하지 않습니다. 복사하여 인증하려는 곳에 `CLAUDE_CODE_OAUTH_TOKEN` 환경 변수로 설정합니다:

302 302 

303**macOS, Linux, WSL**303> [tab] macOS, Linux, WSL

304 304>

305```bash theme={null}305> ```bash theme={null}

306export CLAUDE_CODE_OAUTH_TOKEN=your-token306> export CLAUDE_CODE_OAUTH_TOKEN=your-token

307```307> ```

308 308 

309**Windows PowerShell**309> [tab] Windows PowerShell

310 310>

311```powershell theme={null}311> ```powershell theme={null}

312$env:CLAUDE_CODE_OAUTH_TOKEN = "your-token"312> $env:CLAUDE_CODE_OAUTH_TOKEN = "your-token"

313```313> ```

314 314 

315**Windows CMD**315> [tab] Windows CMD

316 316>

317```batch theme={null}317> ```batch theme={null}

318set CLAUDE_CODE_OAUTH_TOKEN=your-token318> set CLAUDE_CODE_OAUTH_TOKEN=your-token

319```319> ```

320 320 

321이 토큰은 Claude 구독으로 인증하며 Pro, Max, Team, 또는 Enterprise 플랜이 필요합니다. 모델 요청만 수행할 수 있으므로 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 세션을 설정하거나 [claude.ai 커넥터](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)를 가져올 수 없습니다. 로컬로 구성한 MCP 서버는 여전히 작동합니다.321이 토큰은 Claude 구독으로 인증하며 Pro, Max, Ultra, Team, 또는 Enterprise 플랜이 필요합니다. 모델 요청만 수행할 수 있으므로 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 세션을 설정하거나 [claude.ai 커넥터](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)를 가져올 수 없습니다. 로컬로 구성한 MCP 서버는 여전히 작동합니다.

322 322 

323[베어 모드](https://code.claude.com/docs/ko/headless.md#start-faster-with-bare-mode)는 `CLAUDE_CODE_OAUTH_TOKEN`을 읽지 않습니다. 스크립트가 `--bare`를 전달하면, 대신 `ANTHROPIC_API_KEY` 또는 `apiKeyHelper`로 인증하세요.323[베어 모드](https://code.claude.com/docs/ko/headless.md#start-faster-with-bare-mode)는 `CLAUDE_CODE_OAUTH_TOKEN`을 읽지 않습니다. 스크립트가 `--bare`를 전달하면, 대신 `ANTHROPIC_API_KEY` 또는 `apiKeyHelper`로 인증하세요.

43 43 

44## 알림이 나타나는 이유44## 알림이 나타나는 이유

45 45 

46[서버 측 분류기 검토](https://code.claude.com/docs/ko/permission-modes.md#server-side-classifier-review)는 어떤 세션이 분류기 검사를 위해 서버에 요청하는지 나열합니다. Pro, Max, Team 플랜은 절대 알림을 표시하지 않습니다. 알림이 나타날 때 일반적인 원인은 다음과 같습니다:46Pro, Max, Ultra 또는 Team 플랜에서는 알림이 표시되지 않습니다. 어떤 세션이 분류기 검사를 위해 서버에 요청하는지 확인하려면 [서버 측 분류기 검토](https://code.claude.com/docs/ko/permission-modes.md#server-side-classifier-review)를 참조하세요. 알림이 표시되면 다음과 같은 일반적인 원인을 확인하세요:

47 47 

48* **경로에 LLM 게이트웨이 또는 프록시가 있습니다**: 요청 헤더를 제거하거나 다시 작성하고, 인식하지 못하는 요청 필드를 삭제하거나, 응답을 편집하는 게이트웨이입니다. 그러면 서버가 검사 요청을 받지 못하거나 Claude Code가 결과를 받지 못합니다. 구성이나 응답이 게이트웨이를 식별할 때 알림이 이를 명시합니다.48* **경로에 LLM 게이트웨이 또는 프록시가 있습니다**: 요청 헤더를 제거하거나 다시 작성하고, 인식하지 못하는 요청 필드를 삭제하거나, 응답을 편집하는 게이트웨이입니다. 그러면 서버가 검사 요청을 받지 못하거나 Claude Code가 결과를 받지 못합니다. 구성이나 응답이 게이트웨이를 식별할 때 알림이 이를 명시합니다.

49* **서버 측 검사가 아직 플랫폼, 지역 또는 자격 증명에 도달하지 않았습니다**: 플랫폼이나 지역이 검사를 수행하는지 여부는 해당 플랫폼의 출시에 따라 달라집니다. 경로에 게이트웨이나 프록시가 없는데 알림이 계속 나타나면 이것이 가능성 있는 원인입니다. 확인하려면 지원팀이나 회사 관리자에게 문의하거나 `/feedback`으로 보고하세요.49* **서버 측 검사가 아직 플랫폼, 지역 또는 자격 증명에 도달하지 않았습니다**: 플랫폼이나 지역이 검사를 수행하는지 여부는 해당 플랫폼의 출시에 따라 달라집니다. 경로에 게이트웨이나 프록시가 없는데 알림이 계속 나타나면 이것이 가능성 있는 원인입니다. 확인하려면 지원팀이나 회사 관리자에게 문의하거나 `/feedback`으로 보고하세요.

50 50 

51자동 모드에 있는 세션을 확인하려면 Claude Code 프롬프트에서 `/status`를 실행하세요: **자동 모드 서버** 행은 서버의 검사가 세션의 작업을 결정하는 동안 `활성화됨`을 읽고 세션이 폴백된 후 `비활성화됨`을 읽습니다.51자동 모드에 있는 세션을 확인하려면 Claude Code 프롬프트에서 `/status`를 실행하세요: **Auto mode server** 행은 서버의 검사가 세션의 작업을 결정하는 동안 `Enabled`로 표시되고, 세션이 폴백된 후에는 `Disabled`로 표시됩니다.

52 52 

53게이트웨이가 응답을 짧게 자르거나 결과를 Claude Code가 읽을 수 없는 형태로 다시 작성할 때, 이 알림 대신 판정이 없는 거부가 발생합니다. [서버 측 분류기 검토](https://code.claude.com/docs/ko/permission-modes.md#server-side-classifier-review)를 참조하세요.53게이트웨이가 응답을 짧게 자르거나 결과를 Claude Code가 읽을 수 없는 형태로 다시 작성할 때, 이 알림 대신 판정이 없는 거부가 발생합니다. [서버 측 분류기 검토](https://code.claude.com/docs/ko/permission-modes.md#server-side-classifier-review)를 참조하세요.

54 54 

161 161 

162> [!NOTE]162> [!NOTE]

163>163>

164> `/auto-mode-setup`은 Pro, Max, Team, Enterprise 플랜과 Claude Console API 키에서 사용할 수 있습니다. Pro, Max 또는 Team 플랜에서는 v2.1.228 이상이 필요하며, 네이티브 Windows에서는 v2.1.233 이상이 필요합니다. Enterprise 플랜 또는 Claude Console API 키를 사용하는 경우 v2.1.283 이상이 필요합니다. 세션에서 명령이 보이지 않는 경우 [`/auto-mode-setup` returns "Unknown command"](#auto-mode-setup-returns-unknown-command)를 참조하십시오.164> `/auto-mode-setup`은 Pro, Max, Ultra, Team, Enterprise 플랜과 Claude Console API 키에서 사용할 수 있습니다. Pro, Max, Ultra 또는 Team 플랜에서는 v2.1.228 이상이 필요하며, 네이티브 Windows에서는 v2.1.233 이상이 필요합니다. Enterprise 플랜 또는 Claude Console API 키를 사용하는 경우 v2.1.283 이상이 필요합니다. 세션에서 명령이 보이지 않는 경우 [`/auto-mode-setup` returns "Unknown command"](#auto-mode-setup-returns-unknown-command)를 참조하십시오.

165 165 

166### `/auto-mode-setup`이 읽는 항목166### `/auto-mode-setup`이 읽는 항목

167 167 

489 489 

490대부분의 최신 모델이 1M 토큰 윈도우를 가지고 있고 그 상한 근처에서 압축이 이루어지므로, 컨텍스트가 부족해지는 경우는 드뭅니다. 그래도 필요 없는 컨텍스트에 *비용을 지불*할 수는 있습니다. 모든 요청은 전체 대화를 보내므로, 관련 없는 작업 세 개가 쌓인 세션은 네 번째 작업의 매 턴마다 세 작업을 모두 다시 읽습니다. 이는 [캐시가 유효한 동안에는 할인되며](https://code.claude.com/docs/ko/costs.md#why-usage-climbs-in-a-long-session) 캐시가 만료되면 정가가 적용됩니다.490대부분의 최신 모델이 1M 토큰 윈도우를 가지고 있고 그 상한 근처에서 압축이 이루어지므로, 컨텍스트가 부족해지는 경우는 드뭅니다. 그래도 필요 없는 컨텍스트에 *비용을 지불*할 수는 있습니다. 모든 요청은 전체 대화를 보내므로, 관련 없는 작업 세 개가 쌓인 세션은 네 번째 작업의 매 턴마다 세 작업을 모두 다시 읽습니다. 이는 [캐시가 유효한 동안에는 할인되며](https://code.claude.com/docs/ko/costs.md#why-usage-climbs-in-a-long-session) 캐시가 만료되면 정가가 적용됩니다.

491 491 

492[`/usage`](https://code.claude.com/docs/ko/costs)가 가장 먼저 확인할 곳입니다. Pro, Max, Team, Enterprise에서는 사용량을 스킬, 서브에이전트, 플러그인, MCP 서버별로 분류해 보여 줍니다. 또한 긴 컨텍스트나 잦은 캐시 미스 같은 패턴이 사용량의 10%를 넘으면 이를 표시합니다. 그다음 일반적인 해결 방법은 다음과 같습니다.492[`/usage`](https://code.claude.com/docs/ko/costs)가 가장 먼저 확인할 곳입니다. Pro, Max, Ultra, Team, Enterprise에서는 사용량을 스킬, 서브에이전트, 플러그인, MCP 서버별로 분류해 보여 줍니다. 또한 긴 컨텍스트나 잦은 캐시 미스 같은 패턴이 사용량의 10%를 넘으면 이를 표시합니다. 그다음 일반적인 해결 방법은 다음과 같습니다.

493 493 

494* 관련 없는 작업 사이에는 `/clear`를 실행하십시오. 비용이 들지 않으며, 다음 작업이 이전 작업의 기록에 계속 비용을 지불하지 않게 됩니다. `/clear oauth-migration`은 떠나는 세션에 이름을 붙여 나중에 다시 돌아올 수 있게 합니다.494* 관련 없는 작업 사이에는 `/clear`를 실행하십시오. 비용이 들지 않으며, 다음 작업이 이전 작업의 기록에 계속 비용을 지불하지 않게 됩니다. `/clear oauth-migration`은 떠나는 세션에 이름을 붙여 나중에 다시 돌아올 수 있게 합니다.

495* `/compact keep the API changes and the test commands`처럼 초점을 지정하여 `/compact`를 실행하십시오. 긴 세션에서는 `/compact` 자체가 큰 요청입니다. 요약하기 위해 전체 대화를 읽기 때문이며, 캐시가 만료된 후라면 더욱 그렇습니다.495* `/compact keep the API changes and the test commands`처럼 초점을 지정하여 `/compact`를 실행하십시오. 긴 세션에서는 `/compact` 자체가 큰 요청입니다. 요약하기 위해 전체 대화를 읽기 때문이며, 캐시가 만료된 후라면 더욱 그렇습니다.

24 24 

25각 지원되는 채널은 [Bun](https://bun.sh)이 필요한 플러그인입니다. 실제 플랫폼을 연결하기 전에 플러그인 흐름의 실습 데모를 보려면 [fakechat 빠른 시작](#quickstart)을 시도하세요.25각 지원되는 채널은 [Bun](https://bun.sh)이 필요한 플러그인입니다. 실제 플랫폼을 연결하기 전에 플러그인 흐름의 실습 데모를 보려면 [fakechat 빠른 시작](#quickstart)을 시도하세요.

26 26 

27**Telegram**27> [tab] Telegram

28 

29전체 [Telegram 플러그인 소스](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram)를 확인하세요.

30 

31**1. Telegram 봇 만들기**

32 

33Telegram에서 [BotFather](https://t.me/BotFather)를 열고 `/newbot`을 보냅니다. 표시 이름과 `bot`으로 끝나는 고유한 사용자 이름을 지정합니다. BotFather가 반환하는 토큰을 복사합니다.

34 

35**2. 플러그인 설치**

36 

37터미널에서 `claude`를 실행하여 Claude Code를 시작한 다음 프롬프트에 다음을 입력합니다:

38 

39```

40/plugin install telegram@claude-plugins-official

41```

42 

43설치가 실패하면 Claude Code가 보고하는 메시지와 일치시킵니다:

44 

45* `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 다시 시도합니다.

46* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 새로 고친 다음 설치를 다시 시도합니다. 재시도 후에도 같은 메시지가 출력되면 [마켓플레이스에서 플러그인을 찾을 수 없음](https://code.claude.com/docs/ko/plugins/troubleshooting.md#plugin-not-found-in-marketplace)을 참조하세요.

47 

48설치에서 설치 범위를 요청할 때 사용자 범위 옵션을 선택하여 플러그인이 모든 프로젝트에서 사용 가능하도록 합니다. 설치 요약을 확인합니다. `Run /reload-plugins to apply.`를 보고하면 [플러그인 변경 사항을 다시 시작하지 않고 적용](https://code.claude.com/docs/ko/plugins/cli-reference.md#reload-plugins)을 참조하여 플러그인의 구성 명령을 사용 가능하게 합니다.

49 

50**3. 토큰 구성**

51 

52BotFather의 토큰으로 구성 명령을 실행합니다:

53 

54```

55/telegram:configure <token>

56```

57 

58이것은 `~/.claude/channels/telegram/.env`에 저장됩니다. Claude Code를 시작하기 전에 셸 환경에서 `TELEGRAM_BOT_TOKEN`을 설정할 수도 있습니다.

59 

60**4. 채널이 활성화된 상태로 다시 시작**

61 

62Claude Code를 종료하고 채널 플래그로 다시 시작합니다. 이것은 Telegram 플러그인을 시작하여 봇에서 메시지 폴링을 시작합니다:

63 

64```bash theme={null}

65claude --channels plugin:telegram@claude-plugins-official

66```

67 

68**5. 계정 페어링**

69 

70Telegram을 열고 봇에 메시지를 보냅니다. 봇이 페어링 코드로 회신합니다.

71 

72> [!NOTE]

73>28>

74> 봇이 응답하지 않으면 Claude Code가 이전 단계에서 `--channels`로 실행 중인지 확인하세요. 봇은 채널이 활성화된 동안에만 회신할 수 있습니다.29> 전체 [Telegram 플러그인 소스](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram)를 확인하세요.

75 

76Claude Code로 돌아가서 다음을 실행합니다:

77 

78```

79/telegram:access pair <code>

80```

81 

82그런 다음 계정만 메시지를 보낼 수 있도록 액세스를 잠급니다:

83 

84```

85/telegram:access policy allowlist

86```

87 

88**Discord**

89 

90전체 [Discord 플러그인 소스](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord)를 확인하세요.

91 

92**1. Discord 봇 만들기**

93 

94[Discord Developer Portal](https://discord.com/developers/applications)로 이동하여 **New Application**을 클릭하고 이름을 지정합니다. **Bot** 섹션에서 사용자 이름을 만든 다음 **Reset Token**을 클릭하고 토큰을 복사합니다.

95 

96**2. Message Content Intent 활성화**

97 

98봇의 설정에서 **Privileged Gateway Intents**로 스크롤하고 **Message Content Intent**를 활성화합니다.

99 

100**3. 봇을 서버에 초대**

101 

102**OAuth2 > URL Generator**로 이동합니다. `bot` 범위를 선택하고 다음 권한을 활성화합니다:

103 

104* View Channels

105* Send Messages

106* Send Messages in Threads

107* Read Message History

108* Attach Files

109* Add Reactions

110 

111생성된 URL을 열어 봇을 서버에 추가합니다.

112 

113**4. 플러그인 설치**

114 

115터미널에서 `claude`를 실행하여 Claude Code를 시작한 다음 프롬프트에 다음을 입력합니다:

116 

117```

118/plugin install discord@claude-plugins-official

119```

120 

121설치가 실패하면 Claude Code가 보고하는 메시지와 일치시킵니다:

122 

123* `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 다시 시도합니다.

124* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 새로 고친 다음 설치를 다시 시도합니다. 재시도 후에도 같은 메시지가 출력되면 [마켓플레이스에서 플러그인을 찾을 수 없음](https://code.claude.com/docs/ko/plugins/troubleshooting.md#plugin-not-found-in-marketplace)을 참조하세요.

125 

126설치에서 설치 범위를 요청할 때 사용자 범위 옵션을 선택하여 플러그인이 모든 프로젝트에서 사용 가능하도록 합니다. 설치 요약을 확인합니다. `Run /reload-plugins to apply.`를 보고하면 [플러그인 변경 사항을 다시 시작하지 않고 적용](https://code.claude.com/docs/ko/plugins/cli-reference.md#reload-plugins)을 참조하여 플러그인의 구성 명령을 사용 가능하게 합니다.

127 

128**5. 토큰 구성**

129 

130복사한 봇 토큰으로 구성 명령을 실행합니다:

131 

132```

133/discord:configure <token>

134```

135 

136이것은 `~/.claude/channels/discord/.env`에 저장됩니다. Claude Code를 시작하기 전에 셸 환경에서 `DISCORD_BOT_TOKEN`을 설정할 수도 있습니다.

137 

138**6. 채널이 활성화된 상태로 다시 시작**

139 

140Claude Code를 종료하고 채널 플래그로 다시 시작합니다. 이것은 Discord 플러그인을 연결하여 봇이 메시지를 수신하고 응답할 수 있도록 합니다:

141 

142```bash theme={null}

143claude --channels plugin:discord@claude-plugins-official

144```

145 

146**7. 계정 페어링**

147 

148Discord에서 봇에 DM을 보냅니다. 봇이 페어링 코드로 회신합니다.

149 

150> [!NOTE]

151>30>

152> 봇이 응답하지 않으면 Claude Code가 이전 단계에서 `--channels`로 실행 중인지 확인하세요. 봇은 채널이 활성화된 동안에만 회신할 수 있습니다.31> **1. Telegram 봇 만들기**

153 

154Claude Code로 돌아가서 다음을 실행합니다:

155 

156```

157/discord:access pair <code>

158```

159 

160그런 다음 계정만 메시지를 보낼 수 있도록 액세스를 잠급니다:

161 

162```

163/discord:access policy allowlist

164```

165 

166**iMessage**

167 

168전체 [iMessage 플러그인 소스](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/imessage)를 확인하세요.

169 

170iMessage 채널은 Messages 데이터베이스를 직접 읽고 AppleScript를 통해 회신을 보냅니다. macOS가 필요하며 봇 토큰이나 외부 서비스가 필요하지 않습니다.

171 

172**1. 전체 디스크 액세스 권한 부여**

173 

174`~/Library/Messages/chat.db`의 Messages 데이터베이스는 macOS로 보호됩니다. 서버가 처음 읽을 때 macOS는 액세스를 요청합니다. **Allow**를 클릭합니다. 프롬프트는 Terminal, iTerm 또는 IDE와 같이 Bun을 시작한 앱의 이름을 지정합니다.

175 

176프롬프트가 나타나지 않거나 Don't Allow를 클릭한 경우 **System Settings > Privacy & Security > Full Disk Access**에서 수동으로 액세스를 부여하고 터미널을 추가합니다. 이 권한이 없으면 서버가 `authorization denied`로 즉시 종료됩니다.

177 

178**2. 플러그인 설치**

179 

180터미널에서 `claude`를 실행하여 Claude Code를 시작한 다음 프롬프트에 다음을 입력합니다:

181 

182```

183/plugin install imessage@claude-plugins-official

184```

185 

186설치가 실패하면 Claude Code가 보고하는 메시지와 일치시킵니다:

187 

188* `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 다시 시도합니다.

189* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 새로 고친 다음 설치를 다시 시도합니다. 재시도 후에도 같은 메시지가 출력되면 [마켓플레이스에서 플러그인을 찾을 수 없음](https://code.claude.com/docs/ko/plugins/troubleshooting.md#plugin-not-found-in-marketplace)을 참조하세요.

190 

191설치에서 설치 범위를 요청할 때 사용자 범위 옵션을 선택하여 플러그인이 모든 프로젝트에서 사용 가능하도록 합니다.

192 

193설치 요약에서 `Run /reload-plugins to apply.`를 보고하더라도 여기서는 별도로 조치할 필요가 없습니다. 다음 단계에서 다시 시작하면 플러그인이 반영되기 때문입니다.

194 

195**3. 채널이 활성화된 상태로 다시 시작**

196 

197Claude Code를 종료하고 채널 플래그로 다시 시작합니다:

198 

199```bash theme={null}

200claude --channels plugin:imessage@claude-plugins-official

201```

202 

203**4. 자신에게 문자 보내기**

204 

205Apple ID로 로그인한 모든 기기에서 Messages를 열고 자신에게 메시지를 보냅니다. 즉시 Claude에 도달합니다. 자체 채팅은 설정 없이 액세스 제어를 우회합니다.

206 

207> [!NOTE]

208>32>

209> Claude가 보내는 첫 번째 회신은 터미널이 Messages를 제어할 수 있는지 묻는 macOS Automation 프롬프트를 트리거합니다. **OK**를 클릭합니다.33> Telegram에서 [BotFather](https://t.me/BotFather)를 열고 `/newbot`을 보냅니다. 표시 이름과 `bot`으로 끝나는 고유한 사용자 이름을 지정합니다. BotFather가 반환하는 토큰을 복사합니다.

210 34>

211**5. 다른 발신자 허용**35> **2. 플러그인 설치**

212 36>

213기본적으로 자신의 메시지만 통과합니다. 다른 연락처가 Claude에 도달하도록 하려면 해당 핸들을 추가합니다:37> 터미널에서 `claude`를 실행하여 Claude Code를 시작한 다음 프롬프트에 다음을 입력합니다:

38>

39> ```

40> /plugin install telegram@claude-plugins-official

41> ```

42>

43> 설치가 실패하면 Claude Code가 보고하는 메시지와 일치시킵니다:

44>

45> * `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 다시 시도합니다.

46> * `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 새로 고친 다음 설치를 다시 시도합니다. 재시도 후에도 같은 메시지가 출력되면 [마켓플레이스에서 플러그인을 찾을 수 없음](https://code.claude.com/docs/ko/plugins/troubleshooting.md#plugin-not-found-in-marketplace)을 참조하세요.

47>

48> 설치에서 설치 범위를 요청할 때 사용자 범위 옵션을 선택하여 플러그인이 모든 프로젝트에서 사용 가능하도록 합니다. 설치 요약을 확인합니다. `Run /reload-plugins to apply.`를 보고하면 [플러그인 변경 사항을 다시 시작하지 않고 적용](https://code.claude.com/docs/ko/plugins/cli-reference.md#reload-plugins)을 참조하여 플러그인의 구성 명령을 사용 가능하게 합니다.

49>

50> **3. 토큰 구성**

51>

52> BotFather의 토큰으로 구성 명령을 실행합니다:

53>

54> ```

55> /telegram:configure <token>

56> ```

57>

58> 이것은 `~/.claude/channels/telegram/.env`에 저장됩니다. Claude Code를 시작하기 전에 셸 환경에서 `TELEGRAM_BOT_TOKEN`을 설정할 수도 있습니다.

59>

60> **4. 채널이 활성화된 상태로 다시 시작**

61>

62> Claude Code를 종료하고 채널 플래그로 다시 시작합니다. 이것은 Telegram 플러그인을 시작하여 봇에서 메시지 폴링을 시작합니다:

63>

64> ```bash theme={null}

65> claude --channels plugin:telegram@claude-plugins-official

66> ```

67>

68> **5. 계정 페어링**

69>

70> Telegram을 열고 봇에 메시지를 보냅니다. 봇이 페어링 코드로 회신합니다.

71>

72> > [!NOTE]

73> >

74> > 봇이 응답하지 않으면 Claude Code가 이전 단계에서 `--channels`로 실행 중인지 확인하세요. 봇은 채널이 활성화된 동안에만 회신할 수 있습니다.

75>

76> Claude Code로 돌아가서 다음을 실행합니다:

77>

78> ```

79> /telegram:access pair <code>

80> ```

81>

82> 그런 다음 계정만 메시지를 보낼 수 있도록 액세스를 잠급니다:

83>

84> ```

85> /telegram:access policy allowlist

86> ```

214 87 

215```88> [tab] Discord

216/imessage:access allow +1555123456789>

217```90> 전체 [Discord 플러그인 소스](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord)를 확인하세요.

91>

92> **1. Discord 봇 만들기**

93>

94> [Discord Developer Portal](https://discord.com/developers/applications)로 이동하여 **New Application**을 클릭하고 이름을 지정합니다. **Bot** 섹션에서 사용자 이름을 만든 다음 **Reset Token**을 클릭하고 토큰을 복사합니다.

95>

96> **2. Message Content Intent 활성화**

97>

98> 봇의 설정에서 **Privileged Gateway Intents**로 스크롤하고 **Message Content Intent**를 활성화합니다.

99>

100> **3. 봇을 서버에 초대**

101>

102> **OAuth2 > URL Generator**로 이동합니다. `bot` 범위를 선택하고 다음 권한을 활성화합니다:

103>

104> * View Channels

105> * Send Messages

106> * Send Messages in Threads

107> * Read Message History

108> * Attach Files

109> * Add Reactions

110>

111> 생성된 URL을 열어 봇을 서버에 추가합니다.

112>

113> **4. 플러그인 설치**

114>

115> 터미널에서 `claude`를 실행하여 Claude Code를 시작한 다음 프롬프트에 다음을 입력합니다:

116>

117> ```

118> /plugin install discord@claude-plugins-official

119> ```

120>

121> 설치가 실패하면 Claude Code가 보고하는 메시지와 일치시킵니다:

122>

123> * `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 다시 시도합니다.

124> * `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 새로 고친 다음 설치를 다시 시도합니다. 재시도 후에도 같은 메시지가 출력되면 [마켓플레이스에서 플러그인을 찾을 수 없음](https://code.claude.com/docs/ko/plugins/troubleshooting.md#plugin-not-found-in-marketplace)을 참조하세요.

125>

126> 설치에서 설치 범위를 요청할 때 사용자 범위 옵션을 선택하여 플러그인이 모든 프로젝트에서 사용 가능하도록 합니다. 설치 요약을 확인합니다. `Run /reload-plugins to apply.`를 보고하면 [플러그인 변경 사항을 다시 시작하지 않고 적용](https://code.claude.com/docs/ko/plugins/cli-reference.md#reload-plugins)을 참조하여 플러그인의 구성 명령을 사용 가능하게 합니다.

127>

128> **5. 토큰 구성**

129>

130> 복사한 봇 토큰으로 구성 명령을 실행합니다:

131>

132> ```

133> /discord:configure <token>

134> ```

135>

136> 이것은 `~/.claude/channels/discord/.env`에 저장됩니다. Claude Code를 시작하기 전에 셸 환경에서 `DISCORD_BOT_TOKEN`을 설정할 수도 있습니다.

137>

138> **6. 채널이 활성화된 상태로 다시 시작**

139>

140> Claude Code를 종료하고 채널 플래그로 다시 시작합니다. 이것은 Discord 플러그인을 연결하여 봇이 메시지를 수신하고 응답할 수 있도록 합니다:

141>

142> ```bash theme={null}

143> claude --channels plugin:discord@claude-plugins-official

144> ```

145>

146> **7. 계정 페어링**

147>

148> Discord에서 봇에 DM을 보냅니다. 봇이 페어링 코드로 회신합니다.

149>

150> > [!NOTE]

151> >

152> > 봇이 응답하지 않으면 Claude Code가 이전 단계에서 `--channels`로 실행 중인지 확인하세요. 봇은 채널이 활성화된 동안에만 회신할 수 있습니다.

153>

154> Claude Code로 돌아가서 다음을 실행합니다:

155>

156> ```

157> /discord:access pair <code>

158> ```

159>

160> 그런 다음 계정만 메시지를 보낼 수 있도록 액세스를 잠급니다:

161>

162> ```

163> /discord:access policy allowlist

164> ```

218 165 

219핸들은 `+country` 형식의 전화번호 또는 `user@example.com`과 같은 Apple ID 이메일입니다.166> [tab] iMessage

167>

168> 전체 [iMessage 플러그인 소스](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/imessage)를 확인하세요.

169>

170> iMessage 채널은 Messages 데이터베이스를 직접 읽고 AppleScript를 통해 회신을 보냅니다. macOS가 필요하며 봇 토큰이나 외부 서비스가 필요하지 않습니다.

171>

172> **1. 전체 디스크 액세스 권한 부여**

173>

174> `~/Library/Messages/chat.db`의 Messages 데이터베이스는 macOS로 보호됩니다. 서버가 처음 읽을 때 macOS는 액세스를 요청합니다. **Allow**를 클릭합니다. 프롬프트는 Terminal, iTerm 또는 IDE와 같이 Bun을 시작한 앱의 이름을 지정합니다.

175>

176> 프롬프트가 나타나지 않거나 Don't Allow를 클릭한 경우 **System Settings > Privacy & Security > Full Disk Access**에서 수동으로 액세스를 부여하고 터미널을 추가합니다. 이 권한이 없으면 서버가 `authorization denied`로 즉시 종료됩니다.

177>

178> **2. 플러그인 설치**

179>

180> 터미널에서 `claude`를 실행하여 Claude Code를 시작한 다음 프롬프트에 다음을 입력합니다:

181>

182> ```

183> /plugin install imessage@claude-plugins-official

184> ```

185>

186> 설치가 실패하면 Claude Code가 보고하는 메시지와 일치시킵니다:

187>

188> * `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 다시 시도합니다.

189> * `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 새로 고친 다음 설치를 다시 시도합니다. 재시도 후에도 같은 메시지가 출력되면 [마켓플레이스에서 플러그인을 찾을 수 없음](https://code.claude.com/docs/ko/plugins/troubleshooting.md#plugin-not-found-in-marketplace)을 참조하세요.

190>

191> 설치에서 설치 범위를 요청할 때 사용자 범위 옵션을 선택하여 플러그인이 모든 프로젝트에서 사용 가능하도록 합니다.

192>

193> 설치 요약에서 `Run /reload-plugins to apply.`를 보고하더라도 여기서는 별도로 조치할 필요가 없습니다. 다음 단계에서 다시 시작하면 플러그인이 반영되기 때문입니다.

194>

195> **3. 채널이 활성화된 상태로 다시 시작**

196>

197> Claude Code를 종료하고 채널 플래그로 다시 시작합니다:

198>

199> ```bash theme={null}

200> claude --channels plugin:imessage@claude-plugins-official

201> ```

202>

203> **4. 자신에게 문자 보내기**

204>

205> Apple ID로 로그인한 모든 기기에서 Messages를 열고 자신에게 메시지를 보냅니다. 즉시 Claude에 도달합니다. 자체 채팅은 설정 없이 액세스 제어를 우회합니다.

206>

207> > [!NOTE]

208> >

209> > Claude가 보내는 첫 번째 회신은 터미널이 Messages를 제어할 수 있는지 묻는 macOS Automation 프롬프트를 트리거합니다. **OK**를 클릭합니다.

210>

211> **5. 다른 발신자 허용**

212>

213> 기본적으로 자신의 메시지만 통과합니다. 다른 연락처가 Claude에 도달하도록 하려면 해당 핸들을 추가합니다:

214>

215> ```

216> /imessage:access allow +15551234567

217> ```

218>

219> 핸들은 `+country` 형식의 전화번호 또는 `user@example.com`과 같은 Apple ID 이메일입니다.

220 220 

221## 빠른 시작221## 빠른 시작

222 222 

294 294 

295허용 목록은 채널이 선언하는 경우 [권한 릴레이](https://code.claude.com/docs/ko/channels-reference.md#relay-permission-prompts)도 게이트합니다. 채널을 통해 회신할 수 있는 모든 사람이 세션에서 도구 사용을 승인하거나 거부할 수 있으므로 해당 권한을 신뢰하는 발신자만 허용 목록에 추가하세요.295허용 목록은 채널이 선언하는 경우 [권한 릴레이](https://code.claude.com/docs/ko/channels-reference.md#relay-permission-prompts)도 게이트합니다. 채널을 통해 회신할 수 있는 모든 사람이 세션에서 도구 사용을 승인하거나 거부할 수 있으므로 해당 권한을 신뢰하는 발신자만 허용 목록에 추가하세요.

296 296 

297## Enterprise 제어297## 엔터프라이즈 제어

298 298 

299관리자는 사용자가 재정의할 수 없는 두 가지 [관리 설정](https://code.claude.com/docs/ko/settings.md)을 통해 가용성을 제어합니다. 기본값은 인증 방식에 따라 다릅니다:299관리자는 사용자가 재정의할 수 없는 두 가지 [관리형 설정](https://code.claude.com/docs/ko/settings.md)을 통해 사용 가능 여부를 제어합니다. 기본값은 인증 방식에 따라 다릅니다.

300 300 

301* **claude.ai Team 및 Enterprise**: 소유자가 [채널을 활성화](#enable-channels-for-your-organization)할 때까지 채널이 차단됩니다.301* **claude.ai Team 및 Enterprise**: Owner가 [채널을 활성화](#enable-channels-for-your-organization)하기 전까지 채널이 차단됩니다.

302* **Anthropic Console with API key authentication**: 채널이 기본적으로 허용됩니다. 조직이 관리 설정을 배포하는 경우에만 이 설정이 필요합니다.302* **API 키 인증을 사용하는 Anthropic Console**: 채널이 기본적으로 허용됩니다. 이 설정은 조직에서 관리형 설정을 배포하는 경우에만 필요합니다.

303 303 

304모든 경우에 사용자가 `--channels`로 세션에 옵트인할 때까지 채널이 실행되지 않습니다.304어떤 경우든 사용자가 `--channels`로 세션에 채널을 옵트인하기 전까지는 어떤 채널도 실행되지 않습니다.

305 305 

306| 설정 | 목적 | 구성되지 않은 경우 |306| 설정 | 목적 | 구성되지 않은 경우 |

307| :- | :- | :- |307| :- | :- | :- |

308| `channelsEnabled` | 마스터 스위치. 채널이 메시지를 전달하려면 `true`여야 합니다. 채널이 꺼져 있을 때 개발 플래그를 포함한 모든 채널을 차단합니다. [조직에 대해 채널 활성화](#enable-channels-for-your-organization)를 참조하세요. | claude.ai Team 및 Enterprise: 채널 차단됨. Console: 조직이 관리 설정을 배포하지 않는 한 채널 허용됨. 이 경우 이 키가 설정될 때까지 채널 차단됨 |308| `channelsEnabled` | 마스터 스위치입니다. 채널이 메시지를 전달하려면 `true`여야 합니다. 꺼져 있으면 개발 플래그를 포함한 모든 채널이 차단됩니다. [조직에서 채널 활성화하기](#enable-channels-for-your-organization)를 참조하세요. | claude.ai Team 및 Enterprise: 채널이 차단됩니다. Console: 채널이 허용됩니다. 단, 조직에서 관리형 설정을 배포하는 경우에는 이 키가 설정될 때까지 채널이 차단됩니다 |

309| `allowedChannelPlugins` | 채널이 활성화되면 등록할 수 있는 플러그인. 설정되면 Anthropic 유지 관리 목록을 대체합니다. | Anthropic 기본 목록 적용 |309| `allowedChannelPlugins` | 채널이 활성화된 후 등록할 수 있는 플러그인을 지정합니다. 설정하면 Anthropic이 관리하는 목록을 대체합니다. | Anthropic 기본 목록이 적용됩니다 |

310 310 

311조직이 없는 Pro 및 Max 사용자는 이러한 검사를 완전히 건너뜁니다. 채널을 사용할 수 있으며 사용자는 `--channels`로 세션당 옵트인합니다.311조직에 속하지 않은 Pro, Max, Ultra 사용자는 이러한 검사를 완전히 건너뜁니다. 채널을 사용할 수 있으며, 사용자는 세션별로 `--channels`를 사용해 옵트인합니다.

312 312 

313### 조직에 대해 채널 활성화313### 조직에서 채널 활성화하기

314 314 

315조직에 대해 채널을 활성화하려면 Owner 역할이 필요한 [**Organization settings > Claude Code > Channels**](https://claude.ai/admin-settings/claude-code)에서 활성화하거나 관리형 설정에서 `channelsEnabled`를 `true`로 설정합니다.315Owner 역할이 필요한 [**Organization settings > Claude Code > Channels**](https://claude.ai/admin-settings/claude-code)에서 조직의 채널을 활성화하거나, 관리형 설정에서 `channelsEnabled`를 `true`로 설정합니다.

316 316 

317활성화되면 조직의 사용자는 `--channels`를 사용하여 개별 세션에 채널 서버를 옵트인할 수 있습니다. 설정이 비활성화되었거나 설정되지 않은 경우 MCP 서버는 여전히 연결되고 해당 도구가 작동하지만 채널 메시지는 도착하지 않습니다. 시작 경고는 사용자에게 관리자가 설정을 활성화하도록 합니다.317활성화되면 조직의 사용자는 `--channels`를 사용하여 개별 세션에 채널 서버를 옵트인할 수 있습니다. 설정이 비활성화되어 있거나 설정되지 않은 경우에도 MCP 서버는 연결되고 해당 도구도 작동하지만, 채널 메시지는 도착하지 않습니다. 시작 시 경고가 표시되어 관리자에게 설정을 활성화하도록 요청하라고 사용자에게 안내합니다.

318 318 

319### 실행할 수 있는 채널 플러그인 제한319### 실행할 수 있는 채널 플러그인 제한하기

320 320 

321기본적으로 Anthropic 유지 관리 허용 목록의 모든 플러그인이 채널로 등록할 수 있습니다. Team 및 Enterprise 계획의 관리자는 관리 설정에서 `allowedChannelPlugins`을 설정하여 해당 허용 목록을 자신의 목록으로 바꿀 수 있습니다. 이를 사용하여 허용되는 공식 플러그인을 제한하거나 자신의 내부 마켓플레이스에서 채널을 승인하거나 둘 다 수행합니다. 각 항목은 플러그인과 그것이 나오는 마켓플레이스의 이름을 지정합니다:321기본적으로 Anthropic이 관리하는 허용 목록에 있는 모든 플러그인은 채널로 등록할 수 있습니다. Team 및 Enterprise 플랜의 관리자는 관리형 설정에서 `allowedChannelPlugins`를 설정하여 해당 허용 목록을 자체 목록으로 대체할 수 있습니다. 이를 사용해 허용되는 공식 플러그인을 제한하거나, 자체 내부 마켓플레이스의 채널을 승인하거나, 두 가지를 모두 할 수 있습니다. 각 항목은 플러그인과 해당 플러그인이 속한 마켓플레이스를 지정합니다.

322 322 

323```json theme={null}323```json theme={null}

324{324{

331}331}

332```332```

333 333 

334빈 배열을 설정하면 허용 목록의 모든 채널 플러그인을 차단하지만 `--dangerously-load-development-channels`는 여전히 로컬 테스트를 위해 이를 우회할 수 있습니다. 개발 플래그를 포함한 채널을 완전히 차단하려면 대신 `channelsEnabled`를 설정하지 않은 상태로 두세요.334빈 배열을 설정하면 허용 목록에서 모든 채널 플러그인이 차단되지만, 로컬 테스트를 위해 `--dangerously-load-development-channels`로 여전히 이 차단을 우회할 수 있습니다. 개발 플래그를 포함해 채널을 완전히 차단하려면 대신 `channelsEnabled`를 설정하지 않은 상태로 두세요.

335 335 

336이 설정에는 `channelsEnabled: true`가 필요합니다. 사용자가 `--channels`에 조직 목록에 없는 플러그인을 전달하면 Claude Code가 정상적으로 시작되지만 채널이 등록되지 않으며 시작 알림이 플러그인이 조직의 승인된 목록에 없음을 설명합니다. v2 MCP 클라이언트 런타임에서는 Claude Code가 [프로토콜 개정 2026-07-28을 협상하는 채널 서버를 등록하지 않기](https://code.claude.com/docs/ko/mcp.md#push-messages-with-channels) 때문에 채널이 등록되지 않을 수도 있습니다.336이 설정에는 `channelsEnabled: true`가 필요합니다. 사용자가 목록에 없는 플러그인을 `--channels`에 전달하면 Claude Code는 정상적으로 시작되지만 채널은 등록되지 않으며, 시작 시 알림에서 해당 플러그인이 조직의 승인 목록에 없다고 설명합니다. v2 MCP 클라이언트 런타임에서는 Claude Code가 [프로토콜 리비전 2026-07-28을 협상하는 채널 서버를 등록하지 않기](https://code.claude.com/docs/ko/mcp.md#push-messages-with-channels) 때문에 채널 등록이 실패할 수도 있습니다.

337 337 

338## 연구 미리보기338## 연구 미리보기