From 975a9bfa3524828eacc243fd66ad3f225ddbaf6a Mon Sep 17 00:00:00 2001 From: Ziyang Guo <121015044+RerankerGuo@users.noreply.github.com> Date: Wed, 15 Jul 2026 14:22:14 +0800 Subject: [PATCH] docs(worker): align AgentTeams runtime contract --- docs/worker-guide.md | 60 +++++++++++++++++++------------------- docs/zh-cn/worker-guide.md | 60 +++++++++++++++++++------------------- 2 files changed, 60 insertions(+), 60 deletions(-) diff --git a/docs/worker-guide.md b/docs/worker-guide.md index 799edc4f7..4ddb0e4ae 100644 --- a/docs/worker-guide.md +++ b/docs/worker-guide.md @@ -1,6 +1,6 @@ # Worker Guide -Guide for deploying, managing, and troubleshooting HiClaw Worker Agents. +Guide for deploying, managing, and troubleshooting AgentTeams Worker Agents. ## Overview @@ -14,7 +14,7 @@ Workers are lightweight, stateless containers that: Workers are **CRD-backed**. Besides asking the Manager in Matrix, you can: -- Run **`hiclaw create worker` / `hiclaw update worker`** inside `hiclaw-controller` or `hiclaw-manager` (see [faq.md](faq.md)). +- Run **`hiclaw create worker` / `hiclaw update worker`** inside `agentteams-controller` or `agentteams-manager` (see [faq.md](faq.md)). - Apply YAML with **`install/hiclaw-apply.sh`** (forwards to `hiclaw apply -f` in the Manager container). Full field reference: [Declarative Resource Management](declarative-resource-management.md). @@ -48,12 +48,12 @@ If the Manager doesn't have socket access, it will reply with a `docker run` com 3. Copy and run the command on the target host: ```bash -docker run -d --name hiclaw-worker-alice \ - -e HICLAW_WORKER_NAME=alice \ - -e HICLAW_FS_ENDPOINT=http://:9000 \ - -e HICLAW_FS_ACCESS_KEY= \ - -e HICLAW_FS_SECRET_KEY= \ - hiclaw/worker-agent:latest +docker run -d --name agentteams-worker-alice \ + -e AGENTTEAMS_WORKER_NAME=alice \ + -e AGENTTEAMS_FS_ENDPOINT=http://:9000 \ + -e AGENTTEAMS_FS_ACCESS_KEY= \ + -e AGENTTEAMS_FS_SECRET_KEY= \ + agentteams/worker-agent:latest ``` The Manager will provide all the specific values in its reply. @@ -64,7 +64,7 @@ The Manager will provide all the specific values in its reply. ```bash # Check container logs -docker logs hiclaw-worker-alice +docker logs agentteams-worker-alice # Common issues: # - "openclaw.json not found": Manager hasn't created config yet @@ -76,10 +76,10 @@ docker logs hiclaw-worker-alice ```bash # Verify Matrix server is reachable from Worker (via gateway port) -docker exec hiclaw-worker-alice curl -sf http://matrix-local.hiclaw.io:18080/_matrix/client/versions +docker exec agentteams-worker-alice curl -sf http://matrix-local.agentteams.io:8080/_matrix/client/versions # Check Worker's openclaw.json for correct Matrix config -docker exec hiclaw-worker-alice cat /root/hiclaw-fs/agents/alice/openclaw.json | jq '.channels.matrix' +docker exec agentteams-worker-alice cat /root/hiclaw-fs/agents/alice/openclaw.json | jq '.channels.matrix' ``` ### Worker can't access LLM @@ -87,9 +87,9 @@ docker exec hiclaw-worker-alice cat /root/hiclaw-fs/agents/alice/openclaw.json | ```bash # Test AI Gateway access with Worker's key # Note: these commands run inside the Worker container where domain names resolve to Manager's internal IP -docker exec hiclaw-worker-alice curl -sf \ - -H "Authorization: Bearer $(jq -r '.models.providers."hiclaw-gateway".apiKey' /root/hiclaw-fs/agents/alice/openclaw.json)" \ - http://aigw-local.hiclaw.io:8080/v1/models +docker exec agentteams-worker-alice curl -sf \ + -H "Authorization: Bearer $(jq -r '.models.providers."agentteams-gateway".apiKey' /root/hiclaw-fs/agents/alice/openclaw.json)" \ + http://aigw-local.agentteams.io:8080/v1/models # If 401: Check that Worker's consumer key in openclaw.json matches the one in Higress. # If 403: Worker may not be authorized for the AI route. Ask Manager to add. @@ -99,8 +99,8 @@ docker exec hiclaw-worker-alice curl -sf \ ```bash # Test mcporter connectivity (run inside Worker container) -docker exec hiclaw-worker-alice mcporter --transport http \ - --server-url "http://aigw-local.hiclaw.io:8080/mcp-servers/mcp-github/mcp" \ +docker exec agentteams-worker-alice mcporter --transport http \ + --server-url "http://aigw-local.agentteams.io:8080/mcp-servers/mcp-github/mcp" \ --header "Authorization=Bearer " \ call list_repos '{"owner": "test"}' @@ -111,12 +111,12 @@ docker exec hiclaw-worker-alice mcporter --transport http \ ```bash # Stop and remove the container -docker stop hiclaw-worker-alice -docker rm hiclaw-worker-alice +docker stop agentteams-worker-alice +docker rm agentteams-worker-alice # Then ask Manager to recreate the Worker: # "Please recreate the alice worker container" -# Manager will re-run create-worker.sh which regenerates credentials and restarts the container +# The Manager and controller will regenerate credentials and restart the container ``` > Note: Worker config and task data live in MinIO, not in the container. Removing the container does not lose any work. @@ -147,8 +147,8 @@ You can also manually control Workers by asking the Manager: ### File Sync -- **Local to Remote**: Real-time via `mc mirror --watch` -- **Remote to Local**: Periodic pull every 5 minutes +- **Local to Remote**: Change-triggered scan every 5 seconds, followed by `mc mirror` when needed +- **Remote to Local**: On-demand pull after a Manager notification, with a 5-minute fallback ### Config Hot-Reload @@ -161,24 +161,24 @@ When Manager updates Worker's config in MinIO: | Variable | Description | |----------|-------------| -| `HICLAW_WORKER_NAME` | Worker identifier (e.g., `alice`) | -| `HICLAW_MATRIX_URL` | Matrix Homeserver URL (e.g., `http://matrix-local.hiclaw.io:18080`) | -| `HICLAW_AI_GATEWAY_URL` | AI Gateway URL (e.g., `http://aigw-local.hiclaw.io:18080`) | -| `HICLAW_FS_ENDPOINT` | MinIO endpoint URL (e.g., `http://:9000`) | -| `HICLAW_FS_BUCKET` | Bucket name for non-default storage layouts | -| `HICLAW_FS_ACCESS_KEY` | MinIO access key (Worker-specific, generated by Manager) | -| `HICLAW_FS_SECRET_KEY` | MinIO secret key (Worker-specific, generated by Manager) | +| `AGENTTEAMS_WORKER_NAME` | Worker identifier (e.g., `alice`) | +| `AGENTTEAMS_MATRIX_URL` | Matrix Homeserver URL (e.g., `http://matrix-local.agentteams.io:8080`) | +| `AGENTTEAMS_AI_GATEWAY_URL` | AI Gateway URL (e.g., `http://aigw-local.agentteams.io:8080`) | +| `AGENTTEAMS_FS_ENDPOINT` | MinIO endpoint URL (e.g., `http://:9000`) | +| `AGENTTEAMS_FS_BUCKET` | Bucket name for non-default storage layouts (default: `agentteams-storage`) | +| `AGENTTEAMS_FS_ACCESS_KEY` | MinIO access key (Worker-specific, generated by Manager) | +| `AGENTTEAMS_FS_SECRET_KEY` | MinIO secret key (Worker-specific, generated by Manager) | > All values are generated by the Manager and provided in the `docker run` command or set automatically during direct creation. You should not need to set these manually. > -> Runtime scripts now use `HICLAW_MATRIX_URL` and `HICLAW_AI_GATEWAY_URL` directly; legacy aliases are no longer part of the main contract. +> Runtime scripts use `AGENTTEAMS_MATRIX_URL` and `AGENTTEAMS_AI_GATEWAY_URL` directly; legacy variable aliases are not part of the current contract. ### Syncing Files Manually Inside the Worker container, run `hiclaw-sync` to pull the latest config and skill files from MinIO: ```bash -docker exec hiclaw-worker-alice hiclaw-sync +docker exec agentteams-worker-alice hiclaw-sync ``` This is useful after the Manager pushes updated skills or config to MinIO and you want to apply them immediately without waiting for the next sync cycle. diff --git a/docs/zh-cn/worker-guide.md b/docs/zh-cn/worker-guide.md index 3f0070970..2e3e2fdbd 100644 --- a/docs/zh-cn/worker-guide.md +++ b/docs/zh-cn/worker-guide.md @@ -1,6 +1,6 @@ # Worker 使用指南 -HiClaw Worker Agent 的部署、管理和故障排查指南。 +AgentTeams Worker Agent 的部署、管理和故障排查指南。 ## 概述 @@ -14,7 +14,7 @@ Worker 是轻量级无状态容器，负责： Worker 由 **CR** 描述。除在 Matrix 里让 Manager 创建外，你还可以： -- 在 **`hiclaw-controller`** 或 **`hiclaw-manager`** 容器内执行 **`hiclaw create worker` / `hiclaw update worker`**（见 [faq.md](../faq.md)）。 +- 在 **`agentteams-controller`** 或 **`agentteams-manager`** 容器内执行 **`hiclaw create worker` / `hiclaw update worker`**（见 [faq.md](../faq.md)）。 - 使用 **`install/hiclaw-apply.sh`** 应用 YAML（转发到 Manager 容器内的 `hiclaw apply -f`）。 字段说明见 [Declarative Resource Management](../declarative-resource-management.md)。 @@ -48,12 +48,12 @@ Worker 由 **Manager Agent** 或 **controller 声明式 API** 创建。Manager 3. 将命令复制到目标宿主机上执行： ```bash -docker run -d --name hiclaw-worker-alice \ - -e HICLAW_WORKER_NAME=alice \ - -e HICLAW_FS_ENDPOINT=http://:9000 \ - -e HICLAW_FS_ACCESS_KEY= \ - -e HICLAW_FS_SECRET_KEY= \ - hiclaw/worker-agent:latest +docker run -d --name agentteams-worker-alice \ + -e AGENTTEAMS_WORKER_NAME=alice \ + -e AGENTTEAMS_FS_ENDPOINT=http://:9000 \ + -e AGENTTEAMS_FS_ACCESS_KEY= \ + -e AGENTTEAMS_FS_SECRET_KEY= \ + agentteams/worker-agent:latest ``` Manager 会在回复中提供所有具体参数值。 @@ -64,7 +64,7 @@ Manager 会在回复中提供所有具体参数值。 ```bash # 查看容器日志 -docker logs hiclaw-worker-alice +docker logs agentteams-worker-alice # 常见问题： # - "openclaw.json not found"：Manager 尚未创建配置文件 @@ -76,10 +76,10 @@ docker logs hiclaw-worker-alice ```bash # 验证 Matrix 服务器是否可从 Worker 访问（通过网关端口） -docker exec hiclaw-worker-alice curl -sf http://matrix-local.hiclaw.io:18080/_matrix/client/versions +docker exec agentteams-worker-alice curl -sf http://matrix-local.agentteams.io:8080/_matrix/client/versions # 检查 Worker 的 openclaw.json 中的 Matrix 配置 -docker exec hiclaw-worker-alice cat /root/hiclaw-fs/agents/alice/openclaw.json | jq '.channels.matrix' +docker exec agentteams-worker-alice cat /root/hiclaw-fs/agents/alice/openclaw.json | jq '.channels.matrix' ``` ### Worker 无法访问 LLM @@ -87,9 +87,9 @@ docker exec hiclaw-worker-alice cat /root/hiclaw-fs/agents/alice/openclaw.json | ```bash # 使用 Worker 的 key 测试 AI 网关访问 # 注意：以下命令在 Worker 容器内执行，域名会解析到 Manager 的内部 IP -docker exec hiclaw-worker-alice curl -sf \ - -H "Authorization: Bearer $(jq -r '.models.providers."hiclaw-gateway".apiKey' /root/hiclaw-fs/agents/alice/openclaw.json)" \ - http://aigw-local.hiclaw.io:8080/v1/models +docker exec agentteams-worker-alice curl -sf \ + -H "Authorization: Bearer $(jq -r '.models.providers."agentteams-gateway".apiKey' /root/hiclaw-fs/agents/alice/openclaw.json)" \ + http://aigw-local.agentteams.io:8080/v1/models # 401：检查 openclaw.json 中的 Consumer key 是否与 Higress 中的一致 # 403：Worker 可能未被授权访问 AI 路由，请让 Manager 添加权限 @@ -99,8 +99,8 @@ docker exec hiclaw-worker-alice curl -sf \ ```bash # 测试 mcporter 连通性（在 Worker 容器内执行） -docker exec hiclaw-worker-alice mcporter --transport http \ - --server-url "http://aigw-local.hiclaw.io:8080/mcp-servers/mcp-github/mcp" \ +docker exec agentteams-worker-alice mcporter --transport http \ + --server-url "http://aigw-local.agentteams.io:8080/mcp-servers/mcp-github/mcp" \ --header "Authorization=Bearer " \ call list_repos '{"owner": "test"}' @@ -111,12 +111,12 @@ docker exec hiclaw-worker-alice mcporter --transport http \ ```bash # 停止并删除容器 -docker stop hiclaw-worker-alice -docker rm hiclaw-worker-alice +docker stop agentteams-worker-alice +docker rm agentteams-worker-alice # 然后让 Manager 重新创建 Worker： # "请重新创建 alice worker 容器" -# Manager 会重新运行 create-worker.sh，重新生成凭据并重启容器 +# Manager 和 controller 会重新生成凭据并重启容器 ``` > 注意：Worker 的配置和任务数据存储在 MinIO 中，而非容器内。删除容器不会丢失任何工作内容。 @@ -147,8 +147,8 @@ Manager 自动管理 Worker 容器的生命周期： ### 文件同步 -- **本地 → 远端**：通过 `mc mirror --watch` 实时同步 -- **远端 → 本地**：每 5 分钟定期拉取 +- **本地 → 远端**：每 5 秒检测一次变更，并在需要时运行 `mc mirror` +- **远端 → 本地**：收到 Manager 通知后按需拉取，并每 5 分钟兜底拉取一次 ### 配置热重载 @@ -161,24 +161,24 @@ Manager 自动管理 Worker 容器的生命周期： | 变量 | 说明 | 示例值 | |------|------|--------| -| `HICLAW_WORKER_NAME` | Worker 标识符 | `alice` | -| `HICLAW_MATRIX_URL` | Matrix Homeserver URL | `http://matrix-local.hiclaw.io:18080` | -| `HICLAW_AI_GATEWAY_URL` | AI 网关 URL | `http://aigw-local.hiclaw.io:18080` | -| `HICLAW_FS_ENDPOINT` | MinIO 端点 URL | `http://:9000` | -| `HICLAW_FS_BUCKET` | 非默认存储布局下的 bucket 名称 | `hiclaw-storage` | -| `HICLAW_FS_ACCESS_KEY` | MinIO 访问密钥（由 Manager 生成，Worker 专用） | - | -| `HICLAW_FS_SECRET_KEY` | MinIO 密钥（由 Manager 生成，Worker 专用） | - | +| `AGENTTEAMS_WORKER_NAME` | Worker 标识符 | `alice` | +| `AGENTTEAMS_MATRIX_URL` | Matrix Homeserver URL | `http://matrix-local.agentteams.io:8080` | +| `AGENTTEAMS_AI_GATEWAY_URL` | AI 网关 URL | `http://aigw-local.agentteams.io:8080` | +| `AGENTTEAMS_FS_ENDPOINT` | MinIO 端点 URL | `http://:9000` | +| `AGENTTEAMS_FS_BUCKET` | 非默认存储布局下的 bucket 名称 | `agentteams-storage` | +| `AGENTTEAMS_FS_ACCESS_KEY` | MinIO 访问密钥（由 Manager 生成，Worker 专用） | - | +| `AGENTTEAMS_FS_SECRET_KEY` | MinIO 密钥（由 Manager 生成，Worker 专用） | - | > 所有参数值均由 Manager 生成，并在 `docker run` 命令中提供，或在直接创建时自动设置。通常无需手动配置。 > -> 运行时脚本现在直接使用 `HICLAW_MATRIX_URL` 和 `HICLAW_AI_GATEWAY_URL`；旧别名已经不再属于主契约。 +> 运行时脚本直接使用 `AGENTTEAMS_MATRIX_URL` 和 `AGENTTEAMS_AI_GATEWAY_URL`；旧变量别名不属于当前契约。 ### 手动同步文件 在 Worker 容器内执行 `hiclaw-sync`，可立即从 MinIO 拉取最新的配置和技能文件： ```bash -docker exec hiclaw-worker-alice hiclaw-sync +docker exec agentteams-worker-alice hiclaw-sync ``` 当 Manager 向 MinIO 推送了更新的技能或配置，而你不想等待下一个同步周期时，这个命令很有用。