# 에이전트가 작업 공간을 안전하게 사용하게 하기 (/ko/docs/tutorials/agents-safely)

Echolot은 작업 공간을 위한 MCP 서버입니다. Claude Code 같은 AI 에이전트는 요청을 나열하고, 보내고, 응답을 읽을 수 있습니다. 묻지 않고 할 수 있는 일, 물어야 하는 일,
절대 해서는 안 되는 일은 사용자가 정합니다. 비밀 값은 에이전트에 전달되지 않습니다. 이 튜토리얼에서는 Claude Code를 Alpenglow에 연결하고, 에이전트의 전송을 승인하거나
거부하고, 환경을 보호한 다음, Echolot의 내장 어시스턴트로 같은 일을 해 봅니다.

- **소요 시간:** 20분.
- **필요한 것:** [Alpenglow 작업 공간](/docs/tutorials#the-alpenglow-workspace)과 MCP 클라이언트(Claude Code(터미널의 `claude`), Claude Desktop, Cursor, VS Code,
  Codex). 마지막 부분에는 모델 제공업체의 API 키나 Ollama의 로컬 모델이 필요합니다.
- **배우는 내용:** 설정 › 에이전트, 승인, 작업 공간의 에이전트 규칙, 보호된 환경, 비밀 값 대신 에이전트가 보는 것.

## 1. 에이전트 켜기 [#1-turn-agents-on]

1. **Echolot › 설정…**(<kbd>⌘</kbd><kbd>,</kbd>)을 선택하고 **에이전트**를 엽니다.
2. **접근** 아래에서 **에이전트가 열린 작업 공간을 사용하도록 허용**을 켭니다.
3. **에이전트용 도구** 아래에서 **요청**과 **플로**는 켜 둡니다. **요청**은 에이전트가 요청을 나열하고, 읽고, 만들고, 보낼 수 있게 하고, **플로**는 에이전트에 제공한
   플로를 실행합니다. 나머지(**작업 공간**, **환경**, **명세**, **모의 서버**, **MCP 서버**, **기록**, **플로 편집**)는 켜기 전까지 꺼져 있습니다.

무엇을 켜든 제공되지 않는 도구가 있습니다. 정책 자체, 프록시, 인증서, 인증 설정, 스크립트, 제공하지 않은 플로의 시작입니다.

## 2. Claude Code 연결하기 [#2-connect-claude-code]

1. Alpenglow 윈도우에서 페이지 맨 위의 **에이전트**를 선택합니다.
2. **클라이언트 연결** 아래에서 **Claude Code**를 찾아 **명령어 복사**를 선택합니다. 명령은 다음과 같습니다.

   ```sh
   claude mcp add --scope user echolot-alpenglow -- /Applications/Echolot.app/Contents/Helpers/echolot mcp serve /Users/you/Projects/Alpenglow.echolot
   ```

3. 터미널에 붙여넣고 실행합니다.

다른 클라이언트에는 각자의 버튼이 있습니다. **Cursor에 추가**와 **VS Code에 추가**는 설치 링크를 열고, **config.toml 항목 복사**는 Codex용이며, **JSON 복사**는 다른
모든 클라이언트를 위한 `mcpServers` 블록을 제공하고, Claude Desktop의 **Claude에 추가**는 확장 프로그램을 설치합니다. 모든 클라이언트는 `echolot mcp serve`를 실행하며,
이 명령은 호출을 열려 있는 윈도우에 넘기므로 사용자의 승인과 윈도우의 환경이 적용됩니다.

<Edition only="appstore">
  App Store 버전에는 명령줄 도구와 Claude Desktop 확장 프로그램이 포함되어 있지 않습니다. 먼저 [명령줄 도구](/docs/cli)를 따로 설치하십시오. 복사하는 명령과 코드 조각이
  그것을 가리킵니다.
</Edition>

<Shot id="tutorials-agents-connect" alt="Claude Desktop, Claude Code, Cursor, VS Code, Codex용 클라이언트 연결 버튼이 있는 Alpenglow 윈도우의 에이전트 팝오버" />

## 3. 읽고 보내게 하기 [#3-let-it-read-and-send]

1. 터미널에서 `claude`를 시작하고 다음과 같이 요청합니다.

   > Using echolot-alpenglow, list the requests in the Catalog folder, send List products, and tell me the most
   > expensive tent in stock.

2. 에이전트가 요청을 나열하고 **List products**를 묻지 않고 보냅니다. 기본적으로 에이전트는 작업 공간을 읽고 안전한 전송(`GET`, GraphQL 쿼리, MCP 읽기)을 할 수
   있습니다.
3. Echolot에서 **에이전트** 버튼이 이제 **에이전트 · 1**로 표시됩니다. 팝오버의 **최근 호출** 아래에 클라이언트가 나열되며, **허용됨** 스위치로 차단할 수 있습니다.

에이전트의 전송은 보낸 주체와 함께 기록에 남습니다(<kbd>⌘</kbd><kbd>Y</kbd>).

## 4. 데이터를 변경하는 전송 승인하기 [#4-approve-a-send-that-changes-data]

1. 다음과 같이 요청합니다.

   > Place an order for one TNT-MH-2P with Create order.

2. Echolot이 시트를 표시합니다. **Claude Code에서 데이터를 변경할 수 있는 요청을 보내려고 합니다**라는 문구와 함께 요청과 나가는 내용의 미리보기가 나옵니다.
   `Authorization` 헤더는 `Bearer ••••••`로 표시됩니다.
3. 하나를 선택합니다.
   - **한 번 허용**(<kbd>↩</kbd>): 이번 전송만 허용합니다.
   - **이 세션 동안 허용**: 윈도우를 닫을 때까지 이와 같은 전송을 허용합니다.
   - **거부**(<kbd>Esc</kbd>): 에이전트에 거부했다고 알립니다.
4. **한 번 허용**을 선택합니다. 숍이 `201 Created`로 응답하고 에이전트가 새 주문을 보고합니다.

<Shot id="tutorials-agents-approval" alt="승인 시트: Claude Code에서 데이터를 변경할 수 있는 요청을 보내려고 합니다. 거부, 이 세션 동안 허용, 한 번 허용 버튼이 있음" />

## 5. 비밀 값이 닿지 않게 하기 [#5-keep-secrets-out-of-reach]

에이전트에게 묻습니다.

> What is the value of the token variable?

에이전트는 알려 줄 수 없습니다. 비밀 변수의 값은 에이전트에 전달되지 않습니다. 요청, 응답, 오류 어디에 나타나더라도 에이전트에게는 `••••••`로 보입니다. 쓰인 그대로의
값과 JSON, 퍼센트, Base64 형태 모두 해당합니다. 응답 본문을 검색해도 비밀 값에 대한 일치 항목은 세거나 위치를 알려 주지 않습니다.

## 6. 작업 공간의 규칙 정하기 [#6-set-the-workspaces-rules]

기본값은 출발점일 뿐입니다. 작업 공간마다 자체 규칙을 정할 수 있고, 규칙은 `workspace.toml`에 들어가므로 Git을 통해 작업 공간과 함께 이동합니다.

1. 사이드바 아래쪽의 작업 공간 메뉴를 열고 <strong>작업 공간 설정…</strong>을 선택한 다음 <strong>에이전트</strong> 탭을 엽니다.
2. **에이전트의 이 작업 공간 사용 허용**은 이 작업 공간에 한해 에이전트를 끕니다.
3. **에이전트가 할 수 있는 작업** 아래에서 작업 종류마다 **허용**, **묻기**, **거부**(또는 **기본값**)를 지정합니다. **요청 및 환경 읽기**,
   **안전한 전송(GET, GraphQL 쿼리, MCP 읽기)**, **기타 전송**, **보호된 환경으로 전송**, **새로운 호스트로 전송**, **작업 공간 변경**, **삭제**입니다.
   **기타 전송**을 **거부**로 설정합니다.
4. **호스트 및 제한** 아래에서 **허용된 호스트**를 나열하고 **세션당 전송 횟수**나 **분당 전송 횟수**를 설정합니다.
5. **완료**를 선택하고 에이전트에게 주문을 한 번 더 넣으라고 합니다. 시트 없이 거부됩니다.

기본값보다 엄격한 규칙은 즉시 적용됩니다. 묻지 않고 무언가를 허용하게 되는 규칙은, 예를 들어 Git에서 받아 온 작업 공간에 있다면, 사용자를 기다립니다. **에이전트**
팝오버가 무엇을 허용하게 되는지 알려 주고, 규칙을 신뢰하기 전까지 에이전트는 계속 묻습니다. **이 규칙 신뢰**를 선택하면 이 Mac에서 규칙을 수락합니다.

**보호된 환경으로 전송**과 **새로운 호스트로 전송**은 **묻기**나 **거부**만 제공합니다. 에이전트가 묻지 않고 그곳으로 보내게 하는 규칙은 없습니다. 에이전트의 전송에서
발생한 리디렉션은 작업 공간이 모르는 호스트로 비밀 헤더를 전달하지 않습니다.

## 7. 환경 보호하기 [#7-protect-an-environment]

1. 페이지 헤더의 환경 메뉴에서 **Production**을 선택합니다. 보호된 환경이므로 자물쇠와 함께 빨간색으로 표시됩니다.
2. 에이전트에게 **List products**를 다시 보내라고 합니다. 시트에 **Claude Code에서 보호된 환경으로 보내려고 합니다**라고 표시되며, <kbd>↩</kbd>는 아무 동작도 하지
   않습니다. 반드시 선택해야 합니다. **거부**를 선택합니다. (Alpenglow의 Production은 가상의 주소이므로 보내도 어차피 실패합니다.)
3. 직접 <strong>List products</strong>를 보냅니다. 버튼이 <strong>Production에 보내기…</strong>로 표시되고, 알림창이 <strong>Production(으)로 보내시겠습니까?</strong>라고 묻습니다. <strong>취소</strong>가 기본값이며,
   **환경을 전환할 때까지 다시 묻지 않음**은 다른 환경을 선택할 때까지 질문을 멈춥니다. **취소**를 선택합니다.
4. **환경 없음**으로 다시 전환합니다.

환경을 보호하려면 환경 페이지의 **보호됨** 스위치를 켭니다. [보호된 환경](/docs/workspaces/protected-environments)을 참고하십시오.

## 8. 앱 없이: 정책 [#8-without-the-app-policies]

`echolot mcp serve`는 아무도 승인할 수 없는 서버나 CI의 에이전트를 위해 단독으로도 실행됩니다. 그곳에서는 정책이 결정하며, 묻게 되는 모든 것은 거부됩니다.

```sh
echolot mcp serve Alpenglow.echolot --policy readonly
```

| 정책 | 실행되는 것 | 묻는 것(물을 사람이 없으면 거부됨) |
| --- | --- | --- |
| `standard`(기본값) | 읽기와 안전한 전송 | 기타 전송과 변경 |
| `readonly` | 읽기 | 전송. 변경과 삭제는 거부됨 |
| `permissive` | 전송과 변경 | 삭제, 보호된 환경, 새로운 호스트 |

헤드리스에서는 시작할 때 작업 공간에 있던 스크립트만 실행합니다. 자세한 내용은 [에이전트](/docs/ai/agents)와 [`echolot mcp`](/docs/cli/mcp)에 있습니다.

## 9. 내장 어시스턴트 [#9-the-built-in-assistant]

Echolot의 어시스턴트는 모든 페이지 옆의 패널에서 같은 도구와 같은 승인으로 작동합니다.

1. **Echolot › 설정…** › **어시스턴트**를 선택합니다. **제공업체 추가** 아래에서 **제공업체**(Anthropic, OpenAI, Google Gemini 또는 Ollama 같은 OpenAI 호환 서버)를
   고르고, **API 키**나 **주소**를 입력한 다음 **추가**를 선택합니다. 키는 키체인에 보관됩니다.
2. Alpenglow 윈도우에서 <kbd>⌘</kbd><kbd>J</kbd>를 누릅니다(또는 페이지 헤더 끝의 마술봉을 선택합니다).
3. <strong>어시스턴트에게 묻기…</strong>에 `Send every request in Catalog and tell me which checks fail.`을 입력합니다.
4. 작업 공간의 어떤 내용이든 처음 제공업체로 보내기 전에 Echolot이 **Anthropic(으)로 보내시겠습니까?**(또는 선택한 제공업체)라고 묻습니다. **취소**가 기본값이며,
   **허용**을 선택합니다. 제공업체마다 한 번만 묻고, **설정 › 어시스턴트**에서 취소할 수 있습니다. Mac이나 로컬 서버의 모델은 묻지 않습니다.
5. 어시스턴트의 전송도 같은 시트를 거치며, 시트에는 **에이전트에서 …하려고 합니다**라고 표시됩니다.

패널 헤더의 **모델이 보는 내용**은 모델에 무엇이 전송되었는지 정확히 보여 줍니다. [어시스턴트](/docs/ai/assistant)를 참고하십시오.

<Edition only="direct">
  직접 다운로드 버전에서는 어시스턴트가 Mac의 명령줄 에이전트(**CLI 에이전트(ACP)**: Claude Code, Codex, Gemini CLI)도 사용할 수 있습니다.
</Edition>

## 다음 단계 [#next-steps]

- [에이전트](/docs/ai/agents): 모든 설정, 도구 모음, 다른 클라이언트.
- [플로로 자동화하기](/docs/tutorials/automate-with-flows): 사람에게 묻는 승인 블록과 함께 플로를 에이전트에 도구 하나로 제공합니다.
- [개인정보 보호 및 보안](/docs/privacy-and-security): 무엇이 언제 Mac을 떠나는지.