Agent Runtime 实例无法访问外部网络或外部无法访问实

Agent Runtime 网络问题通常表现为三类：Instance 无法访问目标地址、外部请求无法到达 Instance 业务端口，或创建、更新 Tool 时被网络参数校验拒绝。排查时先区分问题发生在 Tool 默认配置、运行中的 Instance，还是 NetworkPolicy、DNSConfig 与端口声明等附加限制。
常见现象
Instance 可以启动，但访问公网 API、私网数据库或内网域名超时或被拒绝。
通过接入域名访问业务端口时返回 404、502，或连接始终无法建立。
创建或更新 Tool 时直接返回 InvalidParameterValue.NetworkMode、MissingParameter.VPCParameters、InvalidParameterValue.SandboxTool 或 UnsupportedOperation.SandboxTool。
排查前准备
先确认当前 CLI 是否已配置云 API 凭证：
agr status -o json --non-interactive
重点关注 Data.Auth.SecretId.Present 和 Data.Auth.SecretKey.Present 是否都为 true。
如果需要先定位对象，再执行诊断查询：
agr tool list -o json --non-interactive   --jq '.Data.Items[] | {ToolId, ToolName, NetworkConfiguration, Status}'
agr instance list -o json --non-interactive   --jq '.Data.Items[] | {InstanceId, ToolId, ToolName, NetworkMode, Status}'
这些命令都是只读查询，不会创建、停止或修改 Tool 和 Instance。
诊断命令
查看 Tool 的默认网络配置、端口声明和 Tool 级 NetworkPolicy：
agr tool get <tool-id> -o json --non-interactive   --jq '.Data | {ToolId, NetworkConfiguration, Ports: .CustomConfiguration.Ports, DNSConfig: .CustomConfiguration.DNSConfig, NetworkPolicy, LogConfiguration}'
查看运行中 Instance 的实际网络模式、端口和实例级 NetworkPolicy：
agr instance get <instance-id> -o json --non-interactive   --jq '.Data | {InstanceId, ToolId, NetworkMode, Status, Ports: .CustomConfiguration.Ports, NetworkPolicy}'
排查前建议记录以下信息，便于后续定位和联系支持：
ToolId
InstanceId
RequestId
Status
NetworkMode
NetworkPolicy
CustomConfiguration.Ports
常见原因与处理
Tool 或 Instance 的 NetworkMode 与目标场景不匹配
访问公网通常需要 PUBLIC，访问私网资源通常需要 VPC。如果 agr tool get 和 agr instance get 查到的网络模式与目标场景不一致，先更新 Tool，再重新启动 Instance。
切换到公网模式：
agr tool update <tool-id>   --network-configuration '{"NetworkMode":"PUBLIC"}'   -o json --non-interactive
切换到 VPC 模式并补齐子网与安全组：
agr tool update <tool-id>   --network-configuration '{"NetworkMode":"VPC","VpcConfig":{"SubnetIds":["subnet-xxxxxxxx"],"SecurityGroupIds":["sg-xxxxxxxx"]}}'   -o json --non-interactive
注意：
agr instance update 当前只公开 --timeout 和 --metadata，不提供网络相关参数。需要让新网络配置生效时，请更新 Tool 后重新启动 Instance。
VPC 模式缺少必要网络参数
如果 NetworkMode 已经是 VPC，但 SubnetIds 或 SecurityGroupIds 缺失、填错，或者与目标私网资源不在同一可达范围，Instance 仍然无法访问私网地址。
排查时重点查看 NetworkConfiguration.VpcConfig 中的 SubnetIds 和 SecurityGroupIds。修复时请一次性提交完整的 NetworkConfiguration，不要只改 NetworkMode 而遗漏 VpcConfig。
显式 DNSConfig 覆盖了默认 DNS
当 Tool 显式配置了 CustomConfiguration.DNSConfig 时，Instance 会优先使用该配置，而不是按当前网络环境注入默认 DNS。私网域名解析异常时，先检查 DNSConfig 是否与预期一致。
如果需要修正 DNS 设置，请使用 agr tool update --custom-configuration 提交新的 CustomConfiguration，再重新启动 Instance 验证解析结果。
NetworkPolicy 拦截了出站请求
如果目标域名、端口、路径或方法不在策略允许范围内，请求会被 Tool 级或 Instance 级 NetworkPolicy 拦截。
注意：
新建 Tool 时，如果不传 NetworkPolicy，默认允许所有流量。
对已存在 Tool 或 Instance 的更新请求，省略 NetworkPolicy 与显式传入 {} 的语义不同：省略表示不更新现有策略，显式传入 {} 表示空策略，按默认拒绝处理。
当前 agr tool update 和 agr instance update 不提供 NetworkPolicy 参数，无法通过 CLI 直接修改现有网络策略。需要修改策略时，请使用 Cloud API。
如果需要修改 Tool 级或 Instance 级 NetworkPolicy，请改用 Cloud API 的 UpdateSandboxTool 或 UpdateSandboxInstance，并在请求体中传入 NetworkPolicy。例如：
{
  "ToolId": "sdt-xxxxxxxx",
  "NetworkPolicy": {}
}
{
  "InstanceId": "ins-xxxxxxxx",
  "NetworkPolicy": {
    "DefaultDecision": "deny",
    "Rules": [
      {
        "Name": "allow-api",
        "Decision": "allow",
        "Resources": [
          {
            "Hosts": [
              "api.example.com"
            ],
            "Ports": [
              "443"
            ]
          }
        ]
      }
    ]
  }
}
如果目标是恢复到“无策略”状态，不建议依赖 null 清空。当前更稳妥的做法是新建一个未配置 NetworkPolicy 的 Tool，再从该 Tool 启动新的 Instance。
业务端口不可达或误用了保留端口
如果业务端口没有写入 CustomConfiguration.Ports，或者监听端口与声明不一致，外部请求无法正确转发到容器进程。
此外，以下端口是平台保留端口，不能用于业务流量：
32000：平台保留用于日志采集，请勿占用。
57890：平台保留用于实例运行管理，请勿占用。
修复时请改用其他业务端口，并确认容器进程在同一端口监听；随后重新查询 Tool 或 Instance，确认 CustomConfiguration.Ports 与实际监听一致。
SANDBOX 模式与 CLSConfig 同时开启
SANDBOX 模式不提供日志投递到 CLS 所需的网络访问能力。如果 Tool 同时配置了 NetworkMode=SANDBOX 和 LogConfiguration.CLSConfig，更新请求会被拒绝，或日志无法按预期投递。
处理方式：
如果必须把日志投递到 CLS，请改用 PUBLIC、INTERNAL_SERVICE 或符合要求的 VPC 模式。
如果必须保持 SANDBOX 模式，请移除 LogConfiguration.CLSConfig。
联系支持时提供的信息
如果完成上述调整后问题仍然存在，提交工单 时建议一并提供：
ToolId
InstanceId
RequestId
Response.Error.Code
Response.Error.Message
当前 NetworkMode
当前 NetworkPolicy
VpcConfig 中的 SubnetIds 和 SecurityGroupIds
目标地址、目标端口，以及失败方向是出站还是入站
相关文档
﻿网络模式﻿
﻿查询沙箱工具﻿
实例无法访问外部网络或外部无法访问实例端口

本页目录：

常见现象

排查前准备

诊断命令

常见原因与处理

Tool 或 Instance 的 NetworkMode 与目标场景不匹配

VPC 模式缺少必要网络参数

显式 DNSConfig 覆盖了默认 DNS

NetworkPolicy 拦截了出站请求

业务端口不可达或误用了保留端口

SANDBOX 模式与 CLSConfig 同时开启

联系支持时提供的信息

相关文档
