번역되지 않은 페이지는 영어로 열리며 영어로 표시됩니다.
이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. Machine-translated from the English page, which is authoritative.
헤드리스 봇
헤드리스 봇은 토큰을 붙여 넣어 줄 사람도, 조용히 발생한 실패를 알아차릴 사람도, "이걸 기억해 줘"라고 말할 사람도 없는 상태로 실행됩니다. 이 가이드는 봇의 ID, 연결 확인, 세 가지 런타임, 봇이 기록하는 내용, 그리고 응답이 없어진 봇을 진단하는 방법을 다룹니다.
1. 봇에 ID 부여하기
loom CLI는 서버 이미지에 포함되어 있으며, 저장소를 클론한 뒤 pip install -e .로 설치합니다.
SDK 패키지(clickhouse-loom)에는 CLI가 없습니다.
셀프 가입을 사용하는 경우. LOOM_SELF_SIGNUP=open으로 설정된 서버에서는 봇이 스스로 가입할 수 있습니다.
loom init --agent nightly-triage --server-url https://<loom> --purpose "Files the nightly failures."
loom init은 다음을 수행합니다.
- 네임스페이스
agent-nightly-triage를 생성합니다(--purpose가 네임스페이스 설명이 됩니다). - 서비스 계정 주체에 해당 네임스페이스의
writer권한을 부여합니다. - 토큰을
~/.loom/token(모드 0600)에 쓰고, URL, 네임스페이스, 조직을~/.loom/config.json에 씁니다(--token-path와--config-path로 위치를 바꿀 수 있습니다). - 클레임 코드와 클레임 페이지 주소(
/oauth/agent-claim)를 출력합니다. 사람이 그 페이지에서 코드를 한 번 입력하고 자신의 비밀번호를 설정하면, 이후에는 네임스페이스 이름과 그 비밀번호로 해당 네임스페이스의 관리자로 로그인합니다. 코드로는 로그인할 수 없으며, 같은 코드로 두 번째 클레임을 시도하면 거부됩니다. 봇의 토큰은 계속 사용할 수 있습니다.
--ttl-days는 토큰 유효 기간을 설정합니다(기본값 365). --org는 서버의 셀프 가입 조직이 아닌 다른 조직을 지정합니다.
CI에서는 파일을 쓰는 대신 토큰을 출력하여 시크릿으로 저장합니다. --no-files를 사용하면 토큰이 출력의 첫 번째 줄에 나옵니다.
loom init --agent ci-reviewer --server-url https://<loom> --no-files | head -n 1 > token.txt
--json을 사용하면 가입 결과가 토큰 없이 JSON으로 출력됩니다. --json --no-files를 함께 사용하면 토큰이 그 JSON 안에 포함되며, 토큰이 출력되는 곳은 그 JSON뿐입니다.
셀프 가입을 사용하지 않는 경우에는 운영자가 토큰을 발급하거나, 사람이 Settings → Tokens에서 봇의 네임스페이스만 읽을 수 있는 토큰을 생성합니다.
loom mint-token --subject ci-reviewer --org <org> --namespaces agent-ci --roles writer \
--service-account --ttl-days 30 --save
역할, 유효 기간, 교체에 대해서는 토큰과 권한 부여를 참고하세요.
2. 처음 실행하기 전에 연결 확인하기
LOOM_BASE_URL=https://<loom> LOOM_API_KEY="$(cat token.txt)" loom doctor --client
loom doctor --client는 플러그인 훅과 SDK가 하는 방식과 같게 서버와 토큰을 확인하고, 각각 어디에서 가져왔는지 알려 줍니다. /v1/health와 namespace.list_mine을 호출해 보고, 토큰이 봇의 네임스페이스에 쓸 수 있는지도 확인합니다. 문제가 있으면 해결 방법을 알려 주는 FAIL 줄로 표시되고 종료 코드는 0이 아니므로, 이 명령은 CI 게이트로 사용할 수 있습니다.
- run: loom doctor --client --server-url ${{ vars.LOOM_BASE_URL }} --token ${{ secrets.LOOM_API_KEY }}
--json은 검사 결과와 문제 목록을 JSON으로 출력하므로, 이를 파싱하는 파이프라인에서 사용할 수 있습니다.
3. 런타임 연결
Claude Agent SDK 또는 claude -p
파일을 통해 Loom을 MCP 서버로 마운트하고 해당 도구만 허용합니다. 헤드리스 실행에는 대화형 OAuth가 없으므로 bearer 토큰을 헤더에 실어 보냅니다.
cat > loom.mcp.json <<EOF
{"mcpServers": {"loom": {"type": "http",
"url": "https://<loom>/mcp?toolset=coding",
"headers": {"Authorization": "Bearer $LOOM_API_KEY"}}}}
EOF
claude -p --mcp-config loom.mcp.json --strict-mcp-config \
--allowedTools "mcp__loom__*" \
--output-format stream-json --verbose \
"Triage the failures in the last nightly run; record each root cause you find."
| 플래그 | 이유 |
|---|---|
--strict-mcp-config |
사용자의 설정이 아니라 파일에 명시된 서버만 봇이 사용하도록 합니다. |
--allowedTools "mcp__loom__*" |
모든 Loom 도구를 사전 승인하여 권한 확인 프롬프트가 실행을 막지 않도록 합니다. |
--output-format stream-json |
첫 번째 메시지는 세션의 system/init입니다(아래 참고). claude -p에서는 이 옵션과 함께 --verbose가 필요합니다. |
--bare |
사용자의 훅, 플러그인, CLAUDE.md를 건너뛰어 동일한 동작을 보장합니다. |
경고: 연결 상태를 기준으로 실행을 확인하세요.
system/init메시지는mcp_servers[]를 나열하며 각 항목에status가 있습니다.loom이connected일 때만 실행을 신뢰하세요. 그렇지 않으면 모델은 메모리 없이 실행된 것입니다.
도구 목록은 ?toolset=으로 선택합니다. 사용 가능한 툴셋은 MCP 툴셋에 나와 있습니다.
claude -p를 실행하는 사용자에게 Loom 플러그인이 설치되어 있으면 해당 훅도 함께 실행됩니다
(Claude Code 플러그인). 플러그인의 멘토 힌트는 플러그인 자체 서버의 도구(mcp__plugin_loom_loom__*)만 따르며, --mcp-config로 지정한 loom 항목은 따르지 않습니다.
Codex codex exec
export LOOM_API_KEY="$(cat token.txt)"
codex exec --json \
-c 'mcp_servers.loom.url="https://<loom>/mcp?toolset=coding"' \
-c 'mcp_servers.loom.bearer_token_env_var="LOOM_API_KEY"' \
"Summarise what we decided about retries; record any decision that is missing."
Codex는 codex가 시작되는 환경에서, 항목에 지정된 변수로부터 bearer 토큰을 읽습니다. Codex 플러그인이 설치되어 있으면 해당 훅도 여기서 실행됩니다
(Codex 플러그인).
봇의 자체 프로세스에서 사용하는 SDK
코딩 에이전트가 아니라 코드로 동작하는 봇이라면 MCP를 건너뛰고 오퍼레이션을 직접 호출합니다.
from loom import Agent
async with Agent(org="acme", namespace="agent-nightly-triage", agent="nightly-triage") as a:
hits = await a.memory.search("flaky tests in the ingest suite", top_k=5)
await a.memory.set(
"flaky/ingest_retry_test",
"Times out against the S3 mock.",
tags=["failure", "ingest"],
)
ans = await a.memory.ask("which suites flaked this week?")
Agent는 서버를 base_url= 또는 LOOM_BASE_URL에서, 토큰을 api_key=, LOOM_API_KEY, ~/.loom/token 순서로 읽습니다. 그 밖의 진입점은 다음과 같습니다.
agent.tools()는 Loom의 동사(loom_remember,loom_recall,loom_ask,loom_offload,loom_fetch,loom_note)를 하나의execute()와 함께 도구 정의로 모델에 제공합니다.agent.session(id)는 에이전트 프레임워크가 보관하는 단위로, 재개, 추가, 플러시, 종료를 지원합니다.- LangGraph 그래프는
LoomStore(loom.integrations.langgraph)를compile(store=...)에 전달하고, Strands 에이전트는LoomMemoryStore(loom.integrations.strands)를 사용합니다. examples/claude_agent_loop.py는 Anthropic SDK를 사용하는 최소한의 루프입니다(ANTHROPIC_API_KEY필요).
Python SDK 레퍼런스와 프레임워크 통합을 참고하세요.
4. 봇이 무엇을 기록할지 결정하기
플러그인은 코딩 세션을 자동으로 캡처합니다. 플러그인 바깥의 봇은 무엇을 기록할지 스스로 결정합니다.
요약하면 다음과 같습니다. 대화 내용 전체가 아니라 결정과 실패를 기록하고, 단계마다 한 번이 아니라 작업 전에 한 번만 회상하며, 완료된 실행의 대화 내용은 memory.set_from_messages에 넘기고, 실행이 참고한 항목은 run.complete(memories_used=[...])로 보고합니다.
각 선택에 대한 자세한 내용은 에이전트 통합에서 다룹니다.
5. 봇이 응답하지 않을 때
봇이 실행되는 머신에서 loom doctor --client를 실행하세요. 일반적인 원인을 각각 한 줄씩 보고합니다.
| 증상 | 원인 |
|---|---|
| 읽기와 쓰기가 다른 서버로 전송됨 | LOOM_BASE_URL이 ~/.loom/config.json과 일치하지 않음 |
| 모든 호출에서 401 발생 | 토큰이 만료되었거나 교체됨 |
| 모든 쓰기에서 403 발생 | 봇이 쓰는 네임스페이스에서 해당 토큰이 viewer 권한임 |
| 캡처가 나타나지 않음 | 백그라운드 flusher가 캡처를 전달하지 못함: 임시 디렉터리에 loom-flush-*.json 파일이 남아 있음 |