AX AgentX

Remote MCP · opencode 优先 · 本机私有配置

客户 MCP 接入

最快路径只需要服务方发放的 MCP URL 和 MCP key：运行配置脚本生成本机私有配置，打开 opencode 后先调用 agentx_whoami，再用返回的资源 id 作为 chipId 跑只读 smoke。

  1. 准备MCP URL 和 MCP key
  2. 运行配置脚本生成客户本机私有配置
  3. 打开opencode 专用 Remote MCP 配置
  4. 确认调用 agentx_whoami({}) 查看授权资源
  5. 烟测使用 permissions.resources[].id 作为 chipId
查看配置脚本 下载 opencode 模板 下载 spawn 示例

运行配置脚本

本地生成，不提交共享

默认输出

脚本会生成 customer.local.json、opencode.json、agent-spawn.example.json、codex.md 和 claude-code.md。包含 key 的文件只放在客户自己的本机私有目录。

环境变量是 fallback

只有客户选择不保存 key，或客户端暂时没有本机密钥库时，才使用 ALI_AGENTX_MCP_KEY 作为临时/高级 fallback。

客户端模板

opencode

推荐

优先使用配置脚本生成的本机私有 opencode.json。下面公开模板默认写入 Ali 公网 Remote MCP 地址；客户只替换自己的 MCP key。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ali-agentx-remote": {
      "type": "remote",
      "url": "http://39.105.87.47/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:ALI_AGENTX_MCP_KEY}"
      }
    }
  }
}
打开模板文件

codex

命令模板

优先把 key 保存到客户电脑自己的本机私有配置或客户端密钥库；环境变量只作为临时 fallback，变量名统一为 ALI_AGENTX_MCP_KEY。

codex mcp add ali-agentx-remote \
  --url <AGENTX_MCP_URL> \
  --bearer-token-env-var ALI_AGENTX_MCP_KEY
打开说明

claude code

HTTP MCP

Claude Code 说明与脚本生成物保持一致：完整 key 只进入客户本机私有配置或客户端密钥库，不贴进聊天、截图或共享文档。

claude mcp add --transport http ali-agentx-remote \
  <AGENTX_MCP_URL> \
  --header "Authorization: Bearer $ALI_AGENTX_MCP_KEY"
打开说明

烟测流程

spawn 示例
  1. 连接 Remote MCP 后列出工具，确认存在 agentx_whoami、agent_spawn、agent_poll、agent_log。
  2. 先调用 agentx_whoami({})，确认当前用户、key fingerprint、可见资源和 cwdExposed=false。
  3. 从 permissions.resources[].id 选择资源，把它作为 agent_spawn.chipId。
  4. 创建只读烟测会话，循环 agent_poll 直到 exited=true，最后用 agent_log 读取结果。
  5. 报错时只反馈时间、客户端、key id/fingerprint、session id 和错误摘要，不发送完整 key。

安全边界

客户只使用 Remote MCP

客户侧不需要服务器登录、部署权限或内部运维信息。所有资源选择都来自 agentx_whoami 返回的授权列表。

不要暴露密钥

不要在聊天、截图、仓库、日志或共享文档里出现完整 MCP KEY、Authorization header、JWT、cookie 或私钥。