Monero

docker-monero

在一个容器中运行自己的 Monero 节点和程序化钱包。它运行官方的 monerod 和 monero-wallet-rpc 版本，并在其前端提供 HTTP API 和 MCP 服务，让脚本和 AI Agent 能够读取区块链、打开钱包、查看余额并发送 XMR。该节点还提供受限 RPC，供 Cake Wallet 和其他钱包连接。

包含内容

部分	功能
monerod	节点。同步区块链，默认使用精简模式。为远程钱包提供 18089 端口上的受限 RPC。
monero-wallet-rpc	每个打开的钱包对应一个进程，通过 API 启动和停止。
HTTP API	8080 端口上的 /v1。节点状态、钱包生命周期、余额、地址、转账历史和发送。
MCP 服务	同一端口上的 /mcp，提供与 HTTP API 相同的操作，作为 AI Agent 可用的工具。
指标	9091 端口上的 Prometheus。

二进制文件来自 getmonero.org，并在构建时使用固定的 SHA-256 哈希进行校验。镜像以非 root 用户运行，并支持只读根文件系统。

快速开始

先在 regtest 上试用：这是一条私有离线区块链，你可以按需挖掘区块，因此不会涉及真实资金。

TOKEN=$(openssl rand -hex 32)
docker run -d --name monero -p 127.0.0.1:8080:8080 \
  -e DOCKER_MONERO_API_TOKEN=$TOKEN -e DOCKER_MONERO_NETWORK=regtest \
  psyb0t/monero
until curl -fs localhost:8080/ready >/dev/null; do sleep 1; done

xmr() { curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' "$@"; }

xmr -X POST localhost:8080/v1/wallets -d '{"name":"alice","password":"pw"}'
ADDR=$(xmr localhost:8080/v1/wallets/alice/addresses | jq -r .primaryAddress)
xmr -X POST localhost:8080/v1/node/regtest/generate-blocks -d "{\"count\":100,\"address\":\"$ADDR\"}"
xmr localhost:8080/v1/wallets/alice/balance

对于主网，请使用 compose 文件：

curl -LO https://raw.githubusercontent.com/psyb0t/docker-monero/main/docker-compose.yml
curl -L -o .env https://raw.githubusercontent.com/psyb0t/docker-monero/main/.env.example
# Set DOCKER_MONERO_API_TOKEN in .env. For the default DOCKER_MONERO_DATA_PATH:
mkdir -p ./data
sudo chown 10001:10001 ./data
docker compose up -d

首次同步主网需要数天，并需要约 105 GiB 的磁盘空间（精简模式）。GET /v1/node/info 会显示同步进度。

使用钱包

钱包必须处于打开状态才能读取或进行支出。打开钱包会启动钱包进程，关闭钱包会保存钱包并停止进程。

xmr -X POST localhost:8080/v1/wallets/alice/open -d '{"password":"pw"}'
xmr localhost:8080/v1/wallets/alice/status       # syncing? how far behind?
xmr -X POST localhost:8080/v1/wallets/alice/transfers \
  -d '{"destinations":[{"address":"4...","amount":"1500000000000"}],"dryRun":true}'
xmr -X POST localhost:8080/v1/wallets/alice/close

金额以原子单位字符串表示（1 XMR = 10^12）。在节点和钱包都同步完成之前，发送操作会被拒绝；dryRun 会估算交易费用，但不会广播交易。其余内容见 docs/api.md 和 api/api.yml 中的 OpenAPI 规范。

写入开关

创建或恢复所需的钱包，然后锁定部署：

• DOCKER_MONERO_READ_ONLY=true 会拒绝所有写入操作：新建或恢复钱包、新建子地址以及发送。打开、关闭和读取仍可正常进行。
• DOCKER_MONERO_ALLOW_TRANSFERS=false 只会拒绝发送操作。
• DOCKER_MONERO_MCP_ALLOW_TRANSFERS=true 是 MCP 客户端发送交易的唯一方式。默认关闭。

Cake Wallet 和其他远程钱包

发布端口 18089，并将钱包的自定义节点设为 http://<your-host>:18089。这是 monerod 的受限 RPC：它只提供钱包所需的功能，不提供任何可控制节点的命令。如果还想将其公布到网络，请设置 DOCKER_MONERO_PUBLIC_NODE=true。

如需要求登录，请设置 DOCKER_MONERO_RPC_LOGIN=username:password，并在钱包的自定义节点设置中输入相同的用户名和密码。用户名不能为空且不能包含冒号，密码长度至少为 16 个字符。留空则禁用登录。参见 configuration.md。

MCP

使用 Authorization: Bearer <token> 将 MCP 客户端连接到 http://localhost:8080/mcp。可用工具以及各模式注册的工具见 docs/mcp.md。

Agent 集成

Agent 可以通过技能（REST 路由、MCP 工具，以及钱包和发送操作相关规则）驱动正在运行的 docker-monero 实例；对于仅支持 stdio 的 MCP 客户端，则可以使用桥接插件。安装后请重启 Agent 会话。

启用插件时，Claude Code 会询问实例 URL 和 API 令牌：

claude plugin marketplace add psyb0t/agents
claude plugin install monero@psyb0t

Codex：

codex plugin marketplace add psyb0t/agents
codex plugin add monero@psyb0t

OpenClaw、技能和 MCP 桥接插件：

openclaw skills install @psyb0t/monero
openclaw plugins install clawhub:@psyb0t/monero

技能和桥接会读取 MONERO_URL（例如 http://localhost:8080）和 MONERO_TOKEN（即 DOCKER_MONERO_API_TOKEN 的值）。支持 Streamable HTTP 的客户端可以跳过桥接，使用 Authorization: Bearer <token> 标头连接到 http://localhost:8080/mcp。该服务也已在 MCP 注册表中列出，名称为 io.github.psyb0t/monero。

本节介绍如何通过 Agent 使用此服务。若要修改此代码库，请阅读 AGENTS.md。

配置

所有设置均为 DOCKER_MONERO_* 环境变量，默认值列于 docs/configuration.md。唯一必需的设置是 DOCKER_MONERO_API_TOKEN。Compose 会将主机目录 DOCKER_MONERO_DATA_PATH（默认为 ./data）挂载到 /data。该目录必须可由 UID/GID 10001 写入；请备份其 wallets 子目录。

请留出足够时间让容器停止：它会保存所有已打开的钱包，并让 monerod 刷新其数据库。使用 docker stop -t 180；compose 文件设置了 stop_grace_period。

文档

• docs/api.md：金额、钱包生命周期、同步、发送、错误代码
• docs/configuration.md：所有变量、端口、磁盘
• docs/mcp.md：MCP 工具
• docs/security.md：服务的保护内容以及你需要负责的事项
• docs/architecture.md：进程、启动、关闭、崩溃处理
• docs/development.md：从源代码构建和测试

开发

make build      # static binary in build/
make test       # unit tests
make test-api   # the real image on regtest
make lint

详情请见 docs/development.md。

许可证

WTFPL。Monero 本身采用其独立的 BSD-3-Clause 许可证。