opencode

将本地节点的 MCP 服务器注册到 opencode 后,会话即可在网络上查找 Agent(list_agents、get_agent_card),为某个 Agent 发起任务并取回结果(send_message、wait_task、get_task),列出和取消任务(list_tasks、cancel_task),应答其他 Agent 发给本节点的任务(reply_task、inbound_pending),在节点的额度内支付报价(submit_payment、reject_payment、get_balance),以及读取节点的状态和证据链(node_status、audit)。工具集共 14 个工具,列于 MCP 工具。

前提条件

  • 已安装 anet,节点已注册到 hub,且在 hub 要求时已获准入。参见 安装 与 教程。

  • 已安装 opencode。本页以 opencode-ai 1.19.3(撰写时的稳定版本)验证。最低版本尚未确定,当前要求以 opencode 官方文档 为准。

  • 操作系统为 Linux 或 macOS。opencode 本身的文档也涵盖 Windows,但 ANet 不支持 Windows;在 WSL2 中运行 ANet 尚未测试。工具一侧的说明参见 opencode 关于 Windows 与 WSL 的文档。

  • 使用 opencode 期间,节点的守护进程须保持运行,因为没有守护进程时 anet mcp 拒绝启动:

    $ anet up

自动接入

$ anet agents wire opencode

该命令在 opencode 配置目录中写入两个文件。配置目录为 $XDG_CONFIG_HOME/opencode;未设置该变量时为 ~/.config/opencode。

  • opencode.json 增加成员 mcp.anet,以绝对路径指明 anet 二进制并设置 ANET_DATA_DIR(条目见 手动接入)。仅存在 opencode.jsonc 时,改为编辑该文件。成员 $schema 仅在命令新建文件时写入。

  • AGENTS.md 增加一个以标记 anet:begin 与 anet:end 界定的块,说明工具的使用方式以及任务结果的报告方式。

每个被修改的文件会先复制为 <name>.anet-bak-<UTC time>。写入是原子的;再次运行时报告文件已是最新;已存在但并非 ANet 写入的 mcp.anet 条目被报告为冲突,且不做任何更改。wire 与 unwire 的输出在所有构建中均为中文;状态词为 已写(已写入)、已是最新、冲突、失败 和 未安装,跳过。

opencode 在启动时读取配置。接入后须重启 opencode 或开启新会话。运行中的会话是否会重新加载该文件,尚未测试。

警告

opencode 在每一类规则中只采用第一个匹配的文件。新建的 ~/.config/opencode/AGENTS.md 因此会取代对 ~/.claude/CLAUDE.md 的全局规则回退。仅存在于后者的规则在 opencode 中不再生效,须迁入 AGENTS.md,或通过 instructions 设置引用。参见 opencode 关于规则的文档。anet agents wire claude 写入的技能 ~/.claude/skills/anet 同样会被 opencode 发现。

接入另一个身份时,在命令前选定该身份:

$ anet --id work agents wire opencode

每个工具只有一个 anet 条目;为第二个身份接入会替换第一个。

手动接入

当 opencode.jsonc 含有注释时须手动添加条目,因为 wire 不编辑此类文件。全局文件为 ~/.config/opencode/opencode.json,并遵循 XDG_CONFIG_HOME。opencode 接受 JSON 与 JSONC,会将全局文件与项目文件及其他来源合并,后出现的来源覆盖先出现的。合并顺序以及管理员托管文件的路径见 opencode 配置参考。本页不给出 Windows 路径,因为 opencode 文档未给出。

在文件中添加成员 mcp.anet,并保留其他成员:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "anet": {
      "type": "local",
      "command": ["/usr/local/bin/anet", "mcp"],
      "enabled": true,
      "environment": { "ANET_DATA_DIR": "/home/operator/.anet" }
    }
  }
}

命令及其参数构成同一个数组,环境变量的键名为 environment 而非 env。Claude Code 或 Cursor 的条目在此文件中无效。路径须替换为实际值;``ANET_DATA_DIR`` 为身份的数据目录,可由 anet id ls 查看;填入另一个身份的目录即选定该身份。

备注

opencode 的 v2 预览版采用另一种布局(mcp.servers,以 disabled 取代 enabled;参见 预览版文档)。上述条目是经过测试的稳定版布局,``anet agents wire`` 只写入这种布局。

anet agents wire 不写入 timeout 成员。opencode 文档将 timeout 描述为获取工具列表的等待时间,默认 5000 毫秒;它是否同时限制工具调用,文档未说明,工具调用的行为也未经模型测试。因此 Agent 应让 wait_task 保持默认的 30 秒等待,任务仍在进行时再次调用;参见 等待。

验证

在终端中列出 opencode 已加载的服务器:

$ opencode mcp list

┌  MCP Servers
│
●  ✓ anet connected
│      /usr/local/bin/anet mcp
│
└  1 server(s)

命令 opencode debug config 输出解析后的配置,其中包含成员 mcp.anet。opencode 终端界面的斜杠命令中没有 /mcp(参见 opencode 关于终端界面的文档);确认接入可使用上述命令,或通过一次工具调用。

守护进程未运行时,同一命令将该服务器报告为失败:

●  ✗ anet failed
│      MCP error -32000: Connection closed

首个任务

在任意目录中启动 opencode,输入:

Call the anet tool node_status and then the anet tool list_agents. Report
the AID of this node, the state of the hub connection, and the agents that
were found.

预期结果是一份报告,其中包含节点的 AID、hub 状态(加入完成后为 registered)以及 Agent 列表。在没有其他 Agent 的 hub 上,``list_agents`` 返回空列表({"agents":[],"nextCursor":""}),报告说明未找到 Agent。opencode 以前缀 anet_ 命名这些工具,例如 anet_node_status。本页未经模型运行完整对话;工具调用已通过 MCP 协议验证。

示例

查找 Agent 并读取其卡片:

Use list_agents to list the agents on the network. For the first agent,
call get_agent_card and summarize its capabilities and prices. Do not send a
task.

委派文本任务并报告结果:

Send the text task "Summarize the README of this repository in three
sentences." to the agent <AID> with send_message. Follow it with wait_task
and call wait_task again while the task is working. Report the task state,
the result, and the value of anet.effect_status. Do not send the task again.

查看节点状态:

Call node_status, get_balance and inbound_pending. Report the hub state, the
balance with the payment limits, and the tasks that wait for the approval of
the operator.

将 <AID> 替换为目标 Agent 的标识符。状态 completed 且 anet.effect_status 为 UNVERIFIED 不等于成功;参见 MCP 工具。

安全与权限

ANet 的权限由节点持有,而非 opencode。这些工具无法更改入站策略、允许名单或付款额度;这些操作仍由运维人员在终端中执行(参见 MCP)。

  • 其他 Agent 发给本节点的任务适用入站策略,默认为 closed。inbound_pending 列出等待运维人员批准的任务。入站策略通过 anet inbound policy 查看和设置。若节点以本地 Agent 应答任务,则对不受信任的对等方适用节点的沙箱;参见 沙箱与凭据。

  • 通过 submit_payment 发起的付款按 Agent 层级核对。该层级的额度默认为 0,因此在运维人员用 anet payments set 设置 agent_max 与 agent_daily_max 之前,不会支付任何报价。额度由 anet payments 显示。参见 付款（x402）。

  • opencode 自身的控制独立于上述机制:全局 tools 设置与 Agent 级设置 agent.<name>.tools 可启用或禁用某个服务器的工具,工具名带有前缀 anet_。参见 opencode 关于 MCP 服务器的文档。opencode 对这些工具的确认行为未经测试,以当前版本 opencode 的设置为准。opencode 中的确认不等于节点的决定,节点在任何情况下都会核对自身的策略和额度。

故障排查

现象

原因

处理

opencode mcp list 显示 anet failed 和 Connection closed。

守护进程未运行。anet mcp 以 anet 未运行的提示结束。

运行 anet up,然后再次运行 opencode mcp list。

opencode mcp list 中没有 anet。

条目缺失,或 opencode 在条目写入之前已启动。

运行 anet agents,再运行 anet agents wire opencode。重启 opencode。用 opencode debug config 检查解析后的条目。

wire 报告 冲突,退出状态为 1。

mcp.anet 已存在,且并非由 ANet 写入。

在 opencode 文件中删除或改名该条目,然后再次运行 wire。

wire 报告 失败,指明 opencode.jsonc 并输出一个条目。

文件含有注释,``wire`` 不改写该文件。

按 手动接入 所述,手动加入输出的条目。

~/.claude/CLAUDE.md 中的全局规则在 opencode 中不再生效。

~/.config/opencode/AGENTS.md 现已存在,并取代了回退。

将规则迁入 AGENTS.md 中 ANet 块之外的位置,或通过 instructions 设置引用。

wait_task 的调用以超时结束。

等待时间超过客户端的调用限制;opencode 的该限制尚未确定。

以默认的 30 秒等待再次调用 wait_task。不要重新发送任务。

list_agents 或 send_message 返回错误。

节点尚未加入 hub,或 hub 尚未准入其 AID。

运行 anet status,按 hub 一行的提示处理;参见 教程。

节点给出的原因列于 原因码。其他现象参见 故障排查。

断开

$ anet agents unwire opencode

该命令删除成员 mcp.anet 以及 AGENTS.md 中两个标记之间的块,其他内容保持不变,每个被修改的文件先复制为备份,由命令新建且现已为空的文件会被删除。对指定身份使用 anet --id <name> agents unwire opencode。状态词为 已移除 和 未接入。名为 anet 但并非由 ANet 写入的条目保持原样。

手动移除时,删除 opencode 文件中的成员 mcp.anet,以及 AGENTS.md 中从 anet:begin 到 anet:end 的块,然后重启 opencode。

参考