docs: simplify Agent Node guide - #554
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 91914dd561
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| # Codex has Read/Write/Edit/Bash/Grep/Glob/WebSearch baked in — you cannot detach individual tools. | ||
| anet node loop my-agent "check open issues" --every 5m | ||
| anet goal list my-agent | ||
| anet goal cancel my-agent <goal-id> |
There was a problem hiding this comment.
When cancelling a goal on the online node described here, anet goal cancel only updates goals.json; the running agent keeps the previous goal state in memory and can continue consuming model quota until it is restarted. The cancel handler in agent-network/bin/cli.ts explicitly warns that a restart is required, so this example should include that step rather than implying the command immediately stops the loop.
Useful? React with 👍 / 👎.
| <a id="environment-variables"></a> | ||
|
|
||
| > ⚠️ **Preview channel only**: not in npm latest — the `anet node create` picker on latest does not list it (see [runtimes table](/en/guide/runtimes#runtimes-—-canonical-table)). Ships to latest once RFC-030 stabilizes. | ||
| ## Node files |
There was a problem hiding this comment.
Existing pages still link to #environment-variables as the Agent Node environment-variable reference—for example, docs-site/docs/en/guide/architecture.md links here for ANET_CODEX_STDIO_DIRECT—but this preserved anchor now lands on the unrelated Node files section and contains no environment-variable guidance. A link checker therefore passes while readers lose the referenced documentation; update those inbound links to the canonical runtime/config documentation or retain a short redirect section here.
Useful? React with 👍 / 👎.
| Documentation-only change. No Docker image, daemon, Hub, model runtime, npm publish, | ||
| or production environment was invoked. This preserves user model quota and avoids |
There was a problem hiding this comment.
This report says the candidate passed a VitePress Docker build on line 38, then says no Docker daemon was invoked here. A Docker build necessarily invokes a Docker daemon, so at least one recorded validation claim is false and the report cannot establish whether the required Docker verification actually ran; record the real command/result consistently.
AGENTS.md reference: AGENTS.md:L7-L8
Useful? React with 👍 / 👎.
| Only task events are sent to the model: | ||
|
|
||
| ### Recurring tasks / the `/loop` scheduler | ||
| - `send_task`: work to execute; invokes the runtime. | ||
| - `send_reply`: a task result; does not invoke the model again. | ||
| - `send_message`: ordinary chat; does not invoke the model again. |
There was a problem hiding this comment.
When the Hub sends a broadcast, it pushes a broadcast SSE event to every target node, and agent-node/src/cli.ts routes it through processInbox, where broadcast explicitly bypasses the non-task filter and invokes the runtime. This list instead implies that only send_task work reaches the model, so an operator may use a broadcast as an informational notice and unexpectedly fan out paid model/tool execution across all nodes; document broadcasts as the other model-triggering event.
Useful? React with 👍 / 👎.
|
|
||
| > OpenCode's built-in Anthropic client sends `x-api-key`. Anthropic-compatible gateways that accept only Bearer authentication, such as Kimi coding, return 401 on that preset; use an OpenCode plugin or custom path that supports the gateway's authentication instead. | ||
|
|
||
| > Agent Node does not read environment variables literally named `TOOLS` or `SYSTEM_PROMPT`. Set tools with `--tools` or config `tools`, and the system prompt with `--prompt` or config `systemPrompt`. |
There was a problem hiding this comment.
In the anet node create/anet node start workflow used throughout this page, --prompt does not set a system prompt: createProfileFromOpts never copies opts.prompt into systemPrompt, and the start path does not forward that option. Only the lower-level agent-node --prompt CLI reads it, so the unqualified advice can silently produce a node without the requested prompt; either identify the direct agent-node command explicitly or tell anet users to set systemPrompt in config.json.
Useful? React with 👍 / 👎.
| | **Prereq** | Install `opencode-ai` at the exact pinned version; export the vendor API key to env (`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`) | | ||
| | **Traits** | Multi-vendor presets (Anthropic native + OpenAI to start); per-node isolated auth.json (mode 0o600); long-lived ACP subprocess, no cold-start; same transport layer as grok-build-acp | | ||
| | **Tools** | opencode built-ins; under a Feishu channel the commhub MCP is always denied (same as grok / claude-code-cli) | | ||
| File tools use the node's launch directory as their workspace. Create and start the node from the intended project, not from `$HOME` or a directory containing unrelated projects or credentials. For background execution: |
There was a problem hiding this comment.
This is not shared behavior for grok-build-acp: before opening the ACP session, agent-node/src/cli.ts calls prepareGrokIsolatedCwd and passes ~/.anet/nodes/<node>/grok-cwd as the runtime cwd. That helper only symlinks entries already present at startup, so a Grok task that creates a new top-level file writes it into the isolated directory rather than the project launch directory. Qualify this rule and point Grok users to the isolated-cwd/output behavior so they do not look for generated artifacts in the wrong workspace.
Useful? React with 👍 / 👎.
| - **Start:** load node config, register/report status, and connect SSE. | ||
| - **Run:** process tasks and report status; reconnect with backoff after connection loss. | ||
| - **Stop:** prefer `anet node stop <alias>` so the node closes its connection and reports offline. | ||
| - **Resume a session:** behavior is runtime-specific. Inspect `anet info <alias>` and the runtime guide instead of editing session/thread ids by hand. |
There was a problem hiding this comment.
anet info <alias> does not print the profile's session or codexThreadId, so it cannot provide the session information this recovery instruction tells the reader to inspect. The CLI exposes a session prefix through anet node ls and supports explicit rebinding with anet node resume <alias> --session <id> where applicable; direct readers to the actual runtime-specific recovery command or config field instead of anet info.
Useful? React with 👍 / 👎.
独立审三条红线全 PASS（P站测试）： - 不声称 source tree 已提供 grok-build-cli（改为「开发分支的 source-only 实验，在进入 npm dist-tag 前不是受支持的安装路径」） - 明写 Neither npm latest nor preview includes a shared Grok TUI（窄修时按 #551 措辞对齐） - grok-build-acp 三处主动推荐，未被误伤（真跑确认它在 agent-node@preview 的 --runtime 列表里） 窄修补回一条唯一信息：OpenCode 的 automatic npx fallback is intentionally disabled —— 复核确认 docs-site 里那 2 处 npx fallback 讲的是另一件事（agent-network 内部 fallback 仍 pin @Preview）， 本条无等价覆盖，属 #554 同款「纠错型否定陈述」，删掉后用户装 opencode-cli 会踩坑并误报 bug。 删除固定版本 pin：2026-05-28 dist-tags 表、opencode-ai@1.18.1 ×3、companion 版本表 —— 头部 README 无残留版本号。 13 个 anet.sh 链接实测全部 200。 复核过、无需处理：provider preset 表与国内/国际 MiniMax 端点区分在 docs-site 有覆盖（guide/basics.md 保留 api.minimaxi.com/anthropic）。
2 participants
What changed
Why
The old page mixed current instructions with release history and runtime-specific examples. Several examples had become stale or unsafe to generalize, and the same facts were duplicated across canonical guides.
User impact
Readers get a shorter node guide with fewer version-sensitive claims and direct links to the pages that own runtime, security, channel, and CLI details.
Validation
git diff --checkagent-network/bin/cli.tsagent-network/package.jsonDocumentation-only change. No Docker, Hub, model runtime, npm publish, or production environment was invoked.