[openclaw 완전 가이드] 5편 openclaw 설정 파일 완전 해설 — openclaw.json 및 AGENTS.md의 모든 것

🏠 홈 › openclaw 완전 가이드 › 5편 · openclaw 설정 파일

⏱ 예상 읽기: 약 9분 입문편 퀀트형 Kai 📚 시리즈 전체보기

← 이전: openclaw doctor — 설치 오류 진단 및 해결 총정리 5 / 30편 다음: Telegram 봇 연결 — 가장 쉬운 채널 세팅 5분 완성 →

설치와 기본 진단을 마쳤다면 이제 '내 AI'를 내 방식대로 동작하도록 만드는 단계입니다. 설정 파일은 AI의 동작 범위, 보안, 채널, 그리고 '어떻게 말할지'까지 결정합니다.

이번 5편에서는 핵심 키워드인 openclaw 설정 파일과 `AGENTS.md` 작성법을 통해, 누구나 쉽게 AI의 행동·권한·응답 톤을 제어하는 방법을 알려드립니다.

지난 편(이전: openclaw doctor — 설치 오류 진단 및 해결 총정리)에서는 문제 진단과 복구 방법을 다뤘습니다. 이제는 튼튼해진 기반 위에서 원하는 대로 에이전트를 커스터마이징할 차례입니다.

📋 이 글의 목차

1. openclaw.json: 핵심 모듈 구조
2. AGENTS.md로 AI 정체성 부여하기
3. 실전 예제: 안전한 기본 설정
4. 권장 보안·운영 패턴
5. FAQ
6. 다음 편 예고

openclaw.json: 에이전트의 두뇌를 제어하는 컨트롤 타워

`~/.openclaw/openclaw.json`은 JSON5 형식을 사용하며, 게이트웨이·채널·스킬·프로바이더·보안 등 운영에 필요한 모든 항목을 담습니다. 핵심 모듈별로 어떤 설정이 중요한지 요약합니다.

Gateway

포트, 바인드 인터페이스, 인증 방식(token 등)을 정의합니다. 외부 노출이 불필요하면 `bind: "loopback"`으로 안전하게 제한하세요.

Channel

텔레그램·디스코드 같은 메시징 채널의 토큰·웹훅 경로·권한을 설정합니다. 각 채널별로 권한 범위를 최소화하는 것이 보안상 중요합니다.

Skills & Provider

스킬은 AI에 '할 수 있는 일'을 부여합니다. 외부 API 호출, 파일 읽기, 터미널 명령 실행 등 민감한 권한은 최소 권한 원칙으로 설계하세요. 프로바이더는 실제 LLM을 지정하고, 주·대체(fallback) 모델을 정의할 수 있습니다.

ℹ️ 참고 JSON5는 주석을 허용하므로 설정에 설명을 적어두면 운영·협업 시 큰 도움이 됩니다.

💡 핵심 요약 openclaw.json은 보안(포트·토큰), 채널, 스킬 권한, 모델 제공자 등 핵심 운영 요소를 한 곳에서 관리합니다.

AGENTS.md: AI에게 역할과 정체성 부여하기

`AGENTS.md`는 AI의 행동 지침서입니다. 이 파일에 '응답 톤', '출력 길이', '우선순위 정보 소스' 등을 명확히 적어두면 매 대화에 일관된 응답을 얻을 수 있습니다.

작성 예시와 원칙

간결하고 명확하게 작성하세요. 먼저 목적(예: 고객지원/기술도움/개인비서)을 정의하고, 금지사항(예: 개인정보 노출 금지)과 우선 참고 자료를 명시합니다.

💡 팁 AGENTS.md를 버전 관리(git)로 관리하고, 변경 시 테스트 대화를 통해 의도대로 반영되는지 확인하세요.

실전 예제: 안전하고 권장되는 기본 설정 뼈대

아래 예시는 운영 중 안정성과 보안을 고려한 권장 기본 설정입니다. 복사해 붙여넣고 환경에 맞게 토큰·경로만 변경하세요.

{
  "meta": { "comment": "나만의 OpenClaw 커스텀 설정 파일" },
  "gateway": { "port": 18789, "bind": "loopback", "auth": { "mode": "token", "token": "YOUR_SUPER_SECRET_TOKEN_HERE" } },
  "agents": { "defaults": { "model": { "primary": "anthropic/claude-sonnet-4-5", "fallbacks": ["openrouter/openai/gpt-4o-mini"] } } },
  "logging": { "redactSensitive": "tools" }
}
    

저장 후에는 설정 적용을 위해 필요 시 게이트웨이를 재시작하세요.

openclaw gateway restart
    

권장 보안·운영 패턴

• API 키는 설정 파일에 직접 작성하지 말고 환경 변수로 분리합니다.
• 민감 권한(파일 접근, 터미널 실행)은 최소 권한만 부여하세요.
• 설정 변경 전 반드시 백업을 수행합니다. (`cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak`)
• AGENTS.md 변경은 테스트 환경에서 먼저 검증한 후 운영에 반영하세요.

⚠️ 주의 설정 파일 오타는 서비스 불안정을 초래할 수 있으니, 수정 후 `openclaw doctor`로 검증하세요.

💡 여기까지 핵심 정리 openclaw.json으로 인프라·권한을 제어하고, AGENTS.md로 AI의 성격과 동작 지침을 부여하면 커스터마이즈된 강력한 에이전트를 운영할 수 있습니다.

자주 묻는 질문 (FAQ)

openclaw.json 파일을 수정하다가 오타를 냈는지 게이트웨이가 켜지지 않아요. 어떡하나요?

`openclaw doctor --fix`로 자동 정리 시도 후에도 문제가 지속되면 백업에서 복원하거나 `openclaw init`으로 초기 설정을 재생성하세요.

설정 파일에 OpenAI나 Claude API 키를 직접 적어도 안전한가요?

보안상 권장하지 않습니다. 환경 변수(`~/.openclaw/.env`)로 분리해 관리하세요.

AGENTS.md 파일은 정확히 어느 폴더에 만들어야 AI가 읽을 수 있나요?

기본적으로 `~/.openclaw/workspace/AGENTS.md`에 두면 즉시 반영됩니다. Workspace 루트에도 둘 수 있습니다.

설정을 바꾸면 무조건 게이트웨이를 껐다가 켜야 하나요?

대부분은 Hot Reload로 반영되지만 포트·보안 모드 등 핵심 변경은 `openclaw gateway restart`가 필요합니다.

---

🔜 다음 편 예고

다음: Telegram 봇 연결 — 가장 쉬운 채널 세팅 5분 완성

다음 편에서는 텔레그램에 OpenClaw을 연결하는 방법을 단계별로 소개합니다. 스마트폰에서 바로 AI에게 지시하는 경험을 준비하세요.

이 글이 도움이 됐다면 댓글로 여러분의 설정 사례를 공유해주세요! 🙌

설정 관련 막힘이 있으면 댓글에 남겨주시면 직접 답변드립니다.

← 이전: openclaw doctor — 설치 오류 진단 및 해결 총정리 📚 목록 다음: Telegram 봇 연결 — 가장 쉬운 채널 세팅 5분 완성 →