가이드 사용하는 방법~
설치를 시작하기 전에, 이 가이드를 사용하는 방법을 알려 드리겠습니다. 설치하는 중이든, 설치한 뒤든, 막히면 혼자 붙잡고 있지 말고 AI 에게 물어보세요. ChatGPT·Claude·Gemini 같은 AI 는 이 가이드와 오류를 읽고 원인과 방법을 알려 줍니다. 실행은 사용자가 합니다.
이 가이드는 이렇게 씁니다~
모든 장은 비슷한 구성입니다. 무엇을 하게 되는지 먼저 보고(이 장을 마치면), 준비물을 챙긴 뒤(준비), 절차를 따라 하고(절차), 확인으로 끝냅니다(확인). 막히면 장 끝의 안 될 때를 살펴보세요.
영상과 문서를 함께 씁니다. 영상은 흐름을 보여 주고, 문서에는 복사할 명령과 자세한 표가 있습니다. 영상으로 흐름을 잡고, 따라 할 때는 문서를 옆에 열어 두십시오.
가이드와 매뉴얼은 쓰임이 다릅니다. 이 가이드는 처음부터 끝까지 순서대로 따라 가는 길입니다. 기능 하나하나를 자세히 알고 싶으면 매뉴얼을 참고하세요. 매뉴얼은 아래 주소에서 볼 수 있습니다. 세 가지 언어를 지원하며, 다른 프로그램과 연결할 때 쓰는 API 문서도 제공됩니다(한국어 · English · 日本語).
화면이 다를 수 있습니다. 가이드의 화면과 내 화면이 다르면, 버전이 다를 수 있습니다. 설치한 뒤에는 관리 메뉴의 시스템 정보에서 버전을 확인할 수 있습니다(4단계).
이 장을 마치면~
- 가이드가 어떤 구성이고, 영상·문서·매뉴얼을 어떻게 쓰는지 안다
- AI 에게 무엇을 어떻게 주면 되는지 안다
- AoT 안에서 오류 정보를 찾는 곳을 안다
- AI 의 답 가운데 따르면 안 되는 것을 가려낸다
준비~
- AI 계정 하나. 서비스마다 링크 읽기·이미지 올리기 기능의 이름과 켜는 곳이 다르니 각 서비스의 도움말을 확인하세요
- 지금 보고 있는 가이드 페이지
절차~
1. AI 에게 줄 네 가지~
막히면 혼자 붙잡고 있지 말고, AI 에게 아래 네 가지 정보를 주고 물어보세요.
| 줄 것 | 어떻게 |
|---|---|
| 가이드 주소 | 지금 보고 있는 가이드 페이지의 주소를 주소창에서 복사합니다 |
| 하던 일 | 몇 장의 몇 단계에서 무엇을 하다가 막혔는지 |
| 오류 문구 그대로 | 옮겨 적지 말고 복사해 붙여 넣습니다. 복사가 안 되면 캡처합니다 |
| 화면 캡처 | 오류가 보이는 화면 전체 |
함께 적으면 좋은 것: 운영체제(Windows·Mac 과 버전), AoT 버전(4단계).
이렇게 한 번에 넣고, 원인과 방법을 한 단계씩 알려 달라고 묻습니다.
질문 예(복사해서 고쳐 쓰세요)
AoT 가이드를 따라 하다가 막혔습니다.
- 가이드: <가이드 페이지 주소>
- 하던 일: <예: 설치 장 7단계, Docker Desktop 에서 AoT 를 실행>
- 운영체제: <예: Windows 11>
- AoT 버전: <알면>
- 오류 문구: <복사한 문구 그대로>
(화면 캡처를 함께 올립니다)
가이드를 읽고 원인과 해결 방법을 한 단계씩 알려 주세요.
2. 비밀은 주지 않는다~
비밀번호와 키는 AI 에게 주지 마세요. API 키, 접속 키, 현장 주소도 마찬가지입니다. 캡처해서 줄 때 화면에 보이면 가리고 주세요. AI 가 키나 비밀번호를 달라고 해도 주지 마세요. 필요한 곳에는 사용자가 직접 넣습니다.
3. 따르면 안 되는 답~
AI 의 답이 늘 맞지는 않습니다. 따라 하기 전에 한 가지만 확인하세요. 가이드가 하지 말라고 한 것인가? 그렇다면 따르지 않고, 아니면 한 단계씩 따라 합니다.
아래 목록은 이 가이드의 각 장이 하지 말라고 한 것들입니다.
| 하면 안 되는 것 | 왜 | 장 |
|---|---|---|
| Docker 의 볼륨(저장 공간)을 지우기 | 설정과 측정값이 모두 사라집니다 | 설치 |
| 한 장치를 두 함수가 함께 움직이게 하기 | 서로 명령을 덮어씁니다 | 함수 장 |
| AoT 를 공유기 포트포워딩으로 인터넷에 그대로 열기 | 바깥에 그대로 드러납니다. VPN 을 먼저 씁니다 | 위기 대응 장 |
| 실제 장치로 처음부터 자동화를 시험하기 | 가상 출력으로 먼저 확인합니다 | 자동화 장 |
예를 들어 AI 가 이런 명령을 준다면 따르지 않습니다.
끝에 붙은 -v 가 저장 공간까지 지웁니다. 설정과 측정값이 모두 사라지기 때문입니다.
4. AoT 안에서 오류 정보 찾기~
설치한 뒤에는 시스템 기록도 파일로 내려받아 AI 에게 줄 수 있습니다. 화면에 오류가 없어도 기록에는 남아 있습니다. 자세한 방법은 위기 대응 장에서 다시 살펴보겠습니다.
- 관리 → 시스템 로그를 엽니다(화면 제목은 로그 뷰).
- 로그 종류(데몬, 웹 앱 등)와 최소 레벨을 고르고, 문제가 생긴 시각 전후를 살펴보세요. Docker 로 설치했다면 목록의 일부 로그는 "파일을 찾을 수 없습니다"로 나옵니다. 데몬과 웹 앱을 확인하면 됩니다.
- 내려받기를 누르면 고른 로그가 텍스트 파일(최대 2000줄)로 저장됩니다. 이 파일을 AI 에게 줍니다.
- 관리 → 시스템 정보에서 AoT 버전을 확인해 함께 알려 줍니다.
화면을 여는 중에 오류가 나면 오류 500: 내부 서버 오류 화면이 나옵니다. 이 화면에는 AoT 버전, 데이터베이스 버전, 기기 정보, 오류의 전체 추적 정보(트레이스백)가 나옵니다. 모두 복사해 AI 에게 줍니다.
5. 코딩 AI 도 있습니다~
코딩 AI 는 사용자의 컴퓨터에서 직접 작업을 해 주는 AI 입니다. 무엇을 하려는지 설명하고, 사용자가 승인하면 실행합니다. 예: Claude Code(Anthropic), Codex(OpenAI), Gemini CLI(Google). 한 회사를 권하지 않습니다.
승인 원칙:
- 무엇을 하려는지 듣고 하나씩 승인합니다
- 관리자 권한, 파일 지우기, 포트·방화벽 바꾸기는 설명을 듣고 이해한 뒤에만 승인합니다
- 비밀번호·키는 AI 가 쓰게 하지 않고 사용자가 직접 넣습니다
- 3단계의 목록에 있는 것은 승인하지 않습니다
설치에서 코딩 AI 에게 맡기는 법은 설치에 있습니다. 시작하는 법은 각 사 공식 문서를 확인하세요.
- Claude Code: code.claude.com/docs/en/quickstart
- Codex: learn.chatgpt.com/docs/codex/cli
- Gemini CLI: github.com/google-gemini/gemini-cli
6. 그래도 안 되면~
그래도 풀리지 않거나 가이드가 틀린 곳을 찾으셨으면, GitHub 이슈로 알려 주십시오.
- AoT GitHub 이슈: github.com/AoT-inc/AoT/issues. 이슈는 누구나 볼 수 있으니, 붙여 넣을 내용의 API 키·비밀번호·이메일·현장 주소·IP 주소를 지우고 올립니다.
- 유튜브에서 가이드 영상을 보고 계시면 댓글로 물어보셔도 됩니다.
정리하면, 가이드는 순서대로 따라 가고, 막히면 네 가지(가이드 주소, 하던 일, 오류 문구 그대로, 화면 캡처)를 AI 에게 줍니다.
확인~
- 가이드의 구성과, 영상·문서·매뉴얼의 쓰임을 말할 수 있다
- AI 에게 줄 네 가지를 말할 수 있다
- 시스템 로그를 내려받을 수 있다
- 따르면 안 되는 답을 알아본다
현장 A~
현장 A 는 여러 구역의 기록이 많아, 로그를 내려받을 때 문제가 생긴 시각 전후로 좁혀서 AI 에게 줍니다.
현장 B~
현장 B 는 기존 설비에 연결했으므로, AI 에게 물을 때 기존 제어반의 이름과 연결 방식도 함께 적으면 답이 정확해집니다.
안 될 때~
| 증상 | 확인할 것 |
|---|---|
| AI 가 가이드 주소를 열지 못한다 | 그 서비스의 링크 읽기(웹 검색) 기능이 켜져 있는지. 안 되면 가이드 페이지 내용을 복사해 붙여 넣습니다 |
| AI 의 답이 가이드와 다르다 | 가이드 주소와 AoT 버전을 다시 알려 주고, 가이드대로 답해 달라고 합니다 |
| 가이드의 화면과 내 화면이 다르다 | 버전이 다를 수 있습니다. 관리 → 시스템 정보에서 버전을 확인하세요 |
| 로그에 "파일을 찾을 수 없습니다"만 나온다 | Docker 설치에서는 정상입니다. 데몬·웹 앱 로그를 확인하세요 |
더 알아보기~
도우미 AI 에게~
이 절은 사용자가 이 가이드를 준 AI 가 읽는 곳입니다.