TL;DR

借助 OpenClaw、Ralph Loop 和 OpenCode 实现全链路自动化，成功构建出 Nexus MCP Server。本文完整记录了从需求分析、方案规划、编码实现到问题排查、架构调整的每一个环节，真实还原 AI 辅助编码工具在复杂开发中的实战表现。所有源码、脚本和规划文档均已上传至 GitHub 仓库 addozhang/nexus-mcp-server[1]。

背景

今天在公司遇到了一个颇具挑战的任务：需要开发一个 Agent 来对比项目依赖的差异，但由于远程仓库的旧版本已被删除，导致使用旧 parent pom 构建失败。我们的思路是让 Agent 自动检索 Nexus 仓库，找到最接近的版本号，从而避免大跨度的版本升级带来额外风险。

我向来不喜欢重复造轮子，内外网搜索了一圈，发现了一个基于 Node 的开源项目 brianveltman/sonatype-mcp[2]，立即进行验证。然而在安装依赖阶段就卡住了——内网仓库缺少一个间接依赖包。

这下正好有了名正言顺造轮子的理由。装上 mcp-builder[3] skill 准备体验一波，但模型能力偏弱，折腾了几次没搞定，加上时间紧张，只好暂时搁置。

下班后想起周末已经把常用的 Coding Agent 和 Skill 都配置到了 OpenClaw[4] 上。这几天零碎时间只创建了几个自己需要的 Agent 和 Skill，还没接过稍微大点的任务。正好拿 Nexus MCP Server 练手，月初还有配额可以用 Claude Opus 4.5，时机非常合适。

技术栈介绍

OpenClaw：AI 自动化编码平台

OpenClaw[5] 是一个开源、本地优先的个人 AI 助手与自主智能体平台，目标是提供一位真正能帮你落地实事的私人 AI 管家。项目最初命名为 Clawdbot，后改名为 Moltbot，2025 年末发布后正式定名为 OpenClaw。

Ralph Loop Skill：结构化开发流程

Ralph Loop[6] 是本次开发使用的核心 Skill，它提供了一套结构化的自动化开发流程，主要包括两个阶段：

• Planning 阶段：分析需求、生成技术规格文档、制定实施计划
• Building 阶段：根据计划自动编写代码、运行测试、生成文档

支持三种工作模式：

• Planning Only：仅生成规划文档
• Building Only：基于现有规划直接开发
• Both：从规划到实施一站式完成（本次选用此模式）

OpenCode：命令行 AI 编码工具

OpenCode[7] 是一个开源的 AI 编程智能体，专为开发者在终端中高效编码而设计。支持多种使用方式：终端 TUI、桌面应用、IDE 插件、Web 界面。本次开发使用 GitHub Copilot 提供的 Claude Opus 4.5 模型。

FastMCP：快速构建 MCP Server

FastMCP[8] 是一个 Python 框架，专门用于快速构建 MCP Server。开发者只需专注业务逻辑，底层协议细节完全由框架处理。

工具链协同

用户需求 → OpenClaw (调度) → Ralph Loop (流程) → OpenCode (执行) → 代码输出

初始条件

动手之前，环境中已具备以下条件：

• OpenCode：已安装，GitHub Copilot 认证完成
• 模型：Claude Opus 4.5（月初配额充足）
• Ralph Loop Skill：支持自动规划→构建的流程
• Docker：提供隔离的开发环境
• Git：版本控制

完整工作流程

需求

本次对制品需求非常明确：

• Maven 仓库：搜索制品、获取版本
• Python (PyPI) 仓库：搜索包、获取版本
• Docker 仓库：列出镜像、获取标签

认证方式：通过 HTTP headers 传递 Nexus URL、用户名和密码。

因此初始 prompt 写得格外简洁：

使用 ralph-loop skill 配合 opencode，为 sonatype nexus pro 3 开发一个 mcp server，并通过 header 
传递 nexus url、username 和 password 支持 maven、python、Docker image 的查询。

需求描述越详细越好——包括 Nexus 版本、期望功能、实现方式等，这些决定了能否实现“端到端生成”，省去交互，直接拿到完整制品，就像视频制作里的“一镜到底”。

但这里给自己埋了个坑：需求中提到通过 HTTP header 传递凭证，我本意默认使用 HTTP 传输模式，结果 OpenClaw 自作主张选了 stdio 模式，最后还在输出中“教育”我说：MCP 使用 stdio 传输，不支持 HTTP 头。

交互

初始 Prompt 之后，只进行了一次交互，涉及：

• 工具选择：Ralph Loop 的模式，选择了“谋而后动”的 Both
• 语言：选 Python（搭配 FastMCP 框架）
• 迭代次数：15（Planning 5 轮 + Building 10 轮）
• 模型：GitHub Copilot 的 Claude Opus 4.5
• 沙箱：Docker

选定之后，OpenClaw 输出了：

• 5 个 spec 文件 (authentication[9]、maven[10]、python[11]、docker[12]、mcp-architecture[13])
• Ralph loop 脚本[14]
• 基础框架：PROMPT.md[15]、AGENTS.md[16]
• Git 初始化

图 1: Planning 阶段自动生成的项目规格文件和配置

尝试启动

第一次尝试 OpenClaw + Ralph Loop + OpenCode 的组合，遇到问题很正常。

问题 1: OpenCode 命令未找到

刚跑起来就报错，提示找不到 OpenCode 命令。我坚持表示已安装并配置好了模型。OpenClaw 反应很快，立刻定位到 OpenCode 的位置并修改了脚本。

- if ! command -v opencode > /dev/null; then  
    OPENCODE_BIN="/home/addo/.opencode/bin/opencode"  
    if ! [ -f "$OPENCODE_BIN" ]; then

根本原因：OpenCode 是在 OpenClaw 启动之后，我在 SSH 会话里才安装的。

问题 2: OpenCode 进程挂起

现象如下：

# 进程运行但无任何输出
PID 16249
运行时间: 21:08
日志: 只有启动信息，之后完全静默

这个问题并不意外，一开始就担心 OpenCode 在纯后台 Bash 模式下无法正常运行。之前在其他 skill coding-agent[17] 中见过类似解决方案，但 Ralph Loop 里没有提及。果断“盲猜”了一句：

是不是 opencode 的运行方式不对，无法在后台运行？

图 2: OpenClaw 通过 tmux 解决 OpenCode 的 TTY 依赖问题

排查过程：

• ✅ 检查认证: opencode auth list → GitHub Copilot 已登录
• ✅ 检查日志: 无新日志产生
• ✅ 简单测试: opencode run "2 + 2" → 同样挂起
• ❌ strace: 权限不足

根本原因：OpenCode 的 run 命令需要真正的 TTY（伪终端），在纯后台 Bash 中会永久等待。

OpenClaw 随后提供了基于 tmux[18] 的 TTY 解决方案，并进行了验证：

# 测试: 在 tmux 中运行 OpenCode
SOCKET="/tmp/openclaw-tmux-sockets/opencode-test.sock"
tmux -S "$SOCKET" new -d -s test
tmux -S "$SOCKET" send-keys "opencode run 'What is 2 + 2?'" Enter
# 结果: ✅ 立即返回 "4"

验证通过后，提供了新脚本 ralph-loop-tmux.sh[19]，核心改进如下：

原方案 (纯后台):
- opencode run "$(cat PROMPT.md)" 2>&1 | tee -a "$LOG_FILE"

新方案 (tmux + TTY):  
  tmux -S "$SOCKET" send-keys "$OPENCODE_BIN run --model $MODEL \"$(cat PROMPT.md)\"" Enter  
  # 等待 shell 提示符返回  
  while [ $ELAPSED -lt $TIMEOUT ]; do  
    OUTPUT=$(tmux -S "$SOCKET" capture-pane -p -t "$SESSION" -S -5)  
    if echo "$OUTPUT" | grep -q "addo@.*$"; then  
      break  
    fi  
  done

Planning 阶段

OpenClaw 直接用 tmux 运行 OpenCode，绕过了脚本测试：

/home/addo/.opencode/bin/opencode run --model github-copilot/claude-opus-4.5 "$(cat PROMPT_PLANNING.md)"

输出了完整的任务实现计划，关键内容：

• Phase 1: 项目基础 (pyproject.toml, 包结构)
• Phase 2: 核心基础设施 (NexusClient, Auth, MCP Server)
• Phase 3-5: Maven/Python/Docker 工具实现
• Phase 6: 测试和质量
• Phase 7: 文档

Building 阶段

Building 阶段顺利启动：

SOCKET="/tmp/openclaw-tmux-sockets/opencode-building.sock"
SESSION="opencode-building"
tmux -S "$SOCKET" new -d -s "$SESSION" -n building
tmux -S "$SOCKET" send-keys '/home/addo/.opencode/bin/opencode run --model github-copilot/claude-opus-4.5 "$(cat PROMPT.md)"' Enter

梳理一下 OpenCode 的工作流程：

11:50:30 - 读取 IMPLEMENTATION_PLAN.md, AGENTS.md, specs/*
11:51:15 - 创建 17 todos
11:51:20 - Task 1.1: 创建 pyproject.toml ✅
11:52:00 - Task 1.2: 创建包结构 ✅
11:53:30 - Task 2.1: 实现 NexusClient ✅
11:55:00 - Task 2.2: 实现认证上下文 ✅
... (省略中间任务)
12:15:00 - 所有测试通过 (26/26) ✅
12:15:30 - 更新文档 (README, AGENTS.md) ✅
12:16:00 - Git commit ✅

最终交付产物：

pyproject.toml
src/nexus_mcp/__init__.py
src/nexus_mcp/__main__.py
src/nexus_mcp/auth.py
src/nexus_mcp/nexus_client.py
src/nexus_mcp/server.py
src/nexus_mcp/tools/__init__.py
src/nexus_mcp/tools/implementations.py
tests/conftest.py
tests/test_nexus_client.py
tests/test_tools.py

文档与发布

基于英文 README 生成了完整的中文版 README.zh-CN.md：

• 完整功能说明
• 详细安装步骤
• 中文示例代码
• 故障排查指南
• 技术栈说明
• 开发历史记录

看了最终的文档，我发现自己犯了一个严重错误：“与基于 HTTP 的 API 不同，MCP 使用 stdio 传输，不支持 HTTP 头。凭证作为参数传递给每个工具调用。”

HTTP Streaming 重构

这次需求更明确了：改用 HTTP streaming transport，通过 HTTP headers 传递凭证。

再次进入 Planning → Building，回炉重造。

Planning 阶段：

• 创建 specs/http-streaming.md 重构规格
• OpenCode 分析 FastMCP HTTP transport 文档
• 生成 14 个重构任务，4 个 Phase
• 预估 10 小时工作量

Building 阶段：

• Phase 8: HTTP Transport 重构 (5 tasks)
  • 更新服务器入口点
  • 实现 HTTP header 依赖注入
  • 重构所有工具签名（移除凭证参数）
• Phase 9: 测试更新 (4 tasks)
  • 新增 test_http_transport.py (10 个测试)
  • 更新所有工具测试
  • 测试从 26 提升至 36 个
• Phase 10: 文档更新 (3 tasks)
  • 更新 README 配置示例
  • 更新 specs 反映 HTTP 架构
• Phase 11: Docker 和部署 (2 tasks)
  • Dockerfile 暴露端口 8000
  • 添加 /health 健康检查端点

实际完成时间：17 分钟。预估的 10 小时，应该是人工实现的成本。看到这里的人，焦虑感是不是更重了？

总结

先别焦虑。这次挑选的案例其实很特殊：将已有的 Nexus REST API 封装成 MCP Server。本质上就是重复性的适配工作——阅读 API 文档、编写调用代码、处理参数、编写测试。技术含量不高，但繁琐且耗时。

这恰恰是 AI 工具最适合的场景。它不是要取代你的技术判断和架构设计能力，而是把你从这些机械的“搬砖”工作中解放出来。当 AI 用 44 分钟完成实现时，你获得的不仅仅是时间节省，更重要的是：可以把精力投入到更有建设性的思考中——比如系统架构设计、技术选型、业务逻辑优化。

回看整个过程，人的价值体现在哪里？

• 需求梳理：明确要做什么、怎么做（虽然第一次没说清楚）
• 工具选择：选择 OpenClaw + Ralph Loop + FastMCP 这个技术栈
• 问题诊断：发现 OpenCode 挂起，定位到 TTY 依赖
• 方向调整：意识到架构问题，决定重构为 HTTP transport
• 质量把控：确保测试覆盖和代码规范

AI 负责的是执行层：生成代码、运行测试、更新文档。这些工作它做得又快又好，但需要你给出明确的方向。

附上量化指标：

注意：总时长 2 小时 13 分，实际上更多是因为出错挂起，而我在处理其他事情。