无头机器人
无头机器人
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
无头机器人在运行时没有人来粘贴令牌、发现静默失败,或者说“记住这个”。本指南涵盖机器人的身份、连接检查、三种运行时、机器人写入的内容,以及如何诊断一个不再有动静的机器人。
1. 为 bot 分配身份
loom CLI 随服务器镜像一同提供,也可以从克隆的仓库用 pip install -e . 安装。SDK 包(clickhouse-loom)不带 CLI。
使用自助注册。 在设置了 LOOM_SELF_SIGNUP=open 的服务器上,bot 可以自行注册:
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)。由一位用户在该页面输入认领码并设置自己的密码,之后即可使用命名空间名称和该密码,以管理员身份登录。认领码本身不能用于登录,也不能再次使用,第二次认领会被拒绝。bot 的令牌仍然有效。
--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 中,这是它唯一出现的位置。
不使用自助注册时,由运维人员签发令牌,或者由用户在 Settings → Tokens 下创建一个只能读取 bot 所用命名空间的令牌:
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,并检查该令牌是否可以写入 bot 的命名空间。每个问题都会输出一行 FAIL,并指明修复方法,同时命令的退出码为非零,因此该命令可以用作 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 |
让 bot 只使用文件中指定的服务器,而不使用用户的配置。 |
--allowedTools "mcp__loom__*" |
预先批准所有 Loom 工具,这样运行不会被权限提示阻塞。 |
--output-format stream-json |
第一条消息是会话的 system/init(见下文)。claude -p 搭配它时需要 --verbose。 |
--bare |
跳过用户的 hook、插件和 CLAUDE.md,以获得一致的行为。 |
警告: 请以连接状态作为准入条件。
system/init消息会列出mcp_servers[],其中每项都带有status。只有当loom的状态为connected时才应信任该次运行;否则模型是在没有记忆的情况下运行的。
用 ?toolset= 选择工具列表;各个工具集列在 MCP 工具集中。
如果运行 claude -p 的用户已安装 Loom 插件,它的 hook 也会运行(见 Claude Code 插件)。它的 mentor 提示只针对插件自带服务器的工具(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 从该条目指定的变量中读取 bearer 令牌,该变量取自 codex 启动时所在的环境。安装 Codex 插件后,它的 hook 在此处也会运行(见 Codex 插件)。
在 bot 自身进程中使用 SDK
如果 bot 是代码而不是编码 agent,可以跳过 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)是 agent 框架所持有的单元:恢复、追加、刷新、关闭。- LangGraph 图把
LoomStore(loom.integrations.langgraph)传给compile(store=...);Strands agent 使用LoomMemoryStore(loom.integrations.strands)。 examples/claude_agent_loop.py是一个使用 Anthropic SDK 的最小循环(需要ANTHROPIC_API_KEY)。
参见 Python SDK 参考和框架集成。
4. 决定 bot 写入什么
插件会自行捕获编码会话,而插件之外的 bot 需要自己决定写入什么。简而言之:记录决策和失败,而不是完整的对话记录;在任务开始前召回一次,而不是每一步都召回;将已完成运行的对话记录交给 memory.set_from_messages;并通过 run.complete(memories_used=[...]) 报告该运行所依赖的内容。Agent 集成对每一项选择都有详细说明。
5. bot 没有动静时
在 bot 所在的机器上运行 loom doctor --client。它会在单独的一行中报告每一种常见原因:
| 现象 | 原因 |
|---|---|
| 读写请求发往了另一台服务器 | LOOM_BASE_URL 与 ~/.loom/config.json 不一致 |
| 每次调用都返回 401 | 令牌已过期或已被轮换 |
| 每次写入都返回 403 | 该令牌在 bot 写入的命名空间中只是 viewer |
| 捕获的内容始终没有出现 | 后台 flusher 没有成功投递:临时目录中滞留着 loom-flush-*.json 文件 |