跳到内容
ClickHouse Loom
Esc
↑↓导航↵打开⌘J预览
本页内容

无头机器人

无头机器人

本页由机器从英文原文翻译,内容以英文原文为准。 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 会执行以下操作:

  1. 创建命名空间 agent-nightly-triage(--purpose 会作为其描述)。
  2. 在该命名空间上授予服务账号主体 writer 角色。
  3. 将令牌写入 ~/.loom/token(权限为 0600),并将 URL、命名空间和组织写入 ~/.loom/config.json(可用 --token-path 和 --config-path 更改路径)。
  4. 输出一个认领码以及认领页面的地址(/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 文件

相关内容

这个页面有帮助吗?