시스템이 이상하게 굴까? 고급 설정과 디버깅 가이드
5 min read
여기까지 왔다면 이미 OpenClaw 를 0부터 동작하는 상태까지 만들어 낸 것입니다. 잘하셨습니다.
이 마지막 글에서는 시스템을 더 안정적이고 유지보수하기 쉽게 만드는 습관을 정리합니다.
이번 글에서 배울 것
- 설정 파일 위치와 두 가지 편집 방식
- 최소 동작 구성 읽는 법
- 환경 변수로 API key 를 안전하게 관리하는 법
- 가장 중요한 디버깅 명령과 자주 보는 오류 이해하기
- 어떤 릴리스 트랙을 선택할지 판단하기
설정 파일은 어디에 있을까?
~/.openclaw/openclaw.json
형식은 JSON5 입니다. 주석과 후행 쉼표를 쓸 수 있어 일반 JSON 보다 훨씬 편합니다.
편집 방법은 두 가지입니다.
- Control UI 의 폼 모드 사용
- Raw JSON 으로 직접 수정
둘 다 같은 파일을 수정합니다.
최소 동작 구성은 어떻게 생겼을까?
{
"agents": {
"list": [
{ "id": "main", "workspace": "~/.openclaw/workspace-main", "default": true }
]
},
"channels": {
"telegram": {
"enabled": true,
"botToken": "your bot token"
}
},
"bindings": [
{ "agentId": "main", "match": { "channel": "telegram" } }
]
}먼저 단순한 구성을 확실히 돌리고, 그다음에 기능을 조금씩 추가하세요.
API key 를 올바르게 보관하기
가능하면 API key 를 config 에 직접 쓰지 않는 편이 안전합니다.
환경 변수를 사용하세요.
# .env 또는 시스템 환경 변수에 설정
ANTHROPIC_API_KEY=sk-ant-xxxxx⚠️ Gateway 를
systemd같은 시스템 서비스로 실행한다면, 해당 서비스가.env를 읽는지 꼭 확인하세요. 그렇지 않으면 API key 를 찾지 못해 "Shell env off" 같은 문제가 생길 수 있습니다.
만능 디버깅 도구
뭔가 이상하다면 가장 먼저 이것부터:
openclaw logs --follow실시간 로그만으로도 많은 문제가 해결됩니다.
자주 보는 오류:
| 오류 | 가능한 원인 |
|---|---|
HTTP 429 |
API 요청이 너무 많아 rate limit 에 걸림 |
unauthorized |
token 또는 gateway.bind 설정 문제 |
content tool_use input field required |
모델 호환성 문제, 공식 docs 확인 |
| Context 가 잘림 | 새 session 을 열거나 compact 수행 |
어떤 릴리스 트랙을 써야 할까?
| 트랙 | 추천 대상 |
|---|---|
| Stable | 일상 사용, 가장 안전한 기본값 |
| Beta | 새 기능을 빨리 써보고 싶은 경우 |
| Dev | 최신 변화를 바로 보고 싶은 개발자 |
💡 큰 업그레이드 전에는
~/.openclaw를 백업해 두면 되돌아갈 길이 생깁니다.
시리즈 완료: 이제 무엇을 할 수 있나?
이 시리즈를 통해 다음을 익혔습니다.
- OpenClaw 의 핵심 개념 이해
- 설치와 첫 실행
- 대시보드 인증 처리
- Telegram 등 채널 연결
- Skills 로 비서 능력 확장
- 메모리와 워크스페이스 관리
- 여러 비서로 작업 분리
- Gateway 를 VPS 로 배치
- Cron 으로 자동화
- 스스로 설정하고 디버깅하기
더 깊은 내용은 항상 docs.openclaw.ai 를 기준으로 확인하세요.
이제 AI 비서는 준비되었습니다. 제대로 일 시켜 봅시다.