{
  "markdown": "# Codex Binance Agent\n\n[![CI](https://github.com/lucyfox199818-collab/codex-binance-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/lucyfox199818-collab/codex-binance-agent/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/lucyfox199818-collab/codex-binance-agent)](https://github.com/lucyfox199818-collab/codex-binance-agent/releases/latest)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-active-2ea44f)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.lucyfox199818-collab%2Fccxt-mcp)\n[![Public MCP smoke](https://github.com/lucyfox199818-collab/codex-binance-agent/actions/workflows/public-mcp-smoke.yml/badge.svg)](https://github.com/lucyfox199818-collab/codex-binance-agent/actions/workflows/public-mcp-smoke.yml)\n[![Dry-run default](https://img.shields.io/badge/trading-dry--run%20default-3b82f6)](#配置交易所)\n\n这是一个让 Codex CLI 通过 MCP 读取加密货币市场、管理 Binance USDT-M\n永续合约，并在本地记录完整交易审计的项目。\n\n[GitHub 仓库](https://github.com/lucyfox199818-collab/codex-binance-agent)\n· [中文主页](https://raw.githack.com/lucyfox199818-collab/codex-binance-agent/main/docs/site/index.html)\n· [演示视频](demo/codex-binance-agent-demo.mp4)\n· [中文社区推广素材](docs/promotion/README.md)\n· [5 分钟公开行情教程](docs/guides/5-minute-public-dry-run-zh.md)\n· [版本记录](CHANGELOG.md)\n· [MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.lucyfox199818-collab%2Fccxt-mcp)\n· [中文试用反馈](https://github.com/lucyfox199818-collab/codex-binance-agent/issues/1)\n· [安全报告](SECURITY.md)\n\n**30 秒了解项目：** Codex 负责当前会话内的研究和交易决策，`ccxt-mcp`\n提供行情、账户与交易工具，项目本地 skills 约束 V1/V2/V3 流程，\n`audit-system` 记录每轮决策、风控、执行和复核。真实交易默认关闭，首次体验无需\nAPI key 即可读取公共行情并运行 dry-run。\n\n项目包含：\n\n- `ccxt-mcp/`：基于 CCXT 的 MCP stdio 服务，提供行情、账户、订单和交易工具。\n- `audit-system/`：本地审计记录、复盘界面，以及只读的 `trading-intel` MCP。\n- `V1.txt`、`V2.txt`、`V3.txt`：三套交易策略和风险边界。\n- `.cursor/skills/trading-v*/`：Codex 执行对应策略时必须遵循的项目本地 skills。\n\n> 风险提示：本项目可以提交真实合约订单。默认配置关闭真实交易并启用\n> dry-run。请先在 dry-run 或 Binance 测试环境中验证。任何策略、模型或示例都不保证盈利，\n> 杠杆交易可能导致本金快速损失。\n\n## 环境要求\n\n- Linux、macOS 或 WSL2。\n- Node.js `>= 22.13.0` 和 npm。\n- Codex CLI。\n- 可选：Binance API key、网络代理、Docker。\n\n检查版本：\n\n```bash\nnode --version\nnpm --version\ncodex --version\n```\n\n安装 Codex CLI（macOS/Linux）：\n\n```bash\ncurl -fsSL https://chatgpt.com/codex/install.sh | sh\ncodex\n```\n\n第一次运行 `codex` 时，按提示使用 ChatGPT 账号或 API key 登录。Codex CLI\n安装和认证方式以 [OpenAI Codex CLI 文档](https://developers.openai.com/codex/cli)\n为准。\n\n## 安装项目\n\n```bash\ngit clone https://github.com/lucyfox199818-collab/codex-binance-agent.git\ncd codex-binance-agent\n\ncd ccxt-mcp\nnpm ci\nnpm run build\n\ncd ../audit-system\nnpm ci\nnpm run build\n\ncd ..\n```\n\n项目根目录没有统一的 npm workspace，因此两个子项目需要分别安装和构建。\n\n## 配置交易所\n\n创建本地环境文件：\n\n```bash\ncp ccxt-mcp/.env.example ccxt-mcp/.env\n```\n\n编辑 `ccxt-mcp/.env`：\n\n```dotenv\n# 可选。无代理时删除这一行或留空。\nTRADINGAGENTS_PROXY_URL=http://127.0.0.1:7890\n\n# 只读取公共行情时可以留空；读取账户或交易时必须填写。\nBINANCE_API_KEY=\nBINANCE_API_SECRET=\n\nCCXT_EXCHANGE_ID=binance\nCCXT_DEFAULT_TYPE=future\nCCXT_SANDBOX=false\nCCXT_TIMEOUT_MS=30000\n\n# 初次使用必须保持以下默认值。\nCCXT_ENABLE_TRADING=false\nCCXT_DRY_RUN=true\n```\n\n`.env` 已被 `.gitignore` 忽略。不要把 API key、secret 或完整 `.env` 提交到 Git、\n粘贴到提示词、日志或网页服务。\n\n建议为该项目创建独立且低权限的 Binance API key：\n\n- 只启用需要的读取和合约交易权限。\n- 禁用提现权限。\n- 配置 IP 白名单，并先用 `ccxt_proxy_ip` 核对出口 IP。\n- 不要复用持有大量资产的主账户密钥。\n\n## 配置 MCP\n\n`ccxt-mcp` 和 `trading-intel` 都是 stdio 服务。通常不需要提前常驻启动，\nCodex 会按 MCP 配置自动启动它们。\n\n先取得项目绝对路径：\n\n```bash\ncd /path/to/codex-binance-agent\npwd\n```\n\n将下面的 `/ABS/PATH/codex-binance-agent` 替换为 `pwd` 输出，然后注册 MCP：\n\n```bash\ncodex mcp add ccxt -- \\\n  bash -lc 'cd /ABS/PATH/codex-binance-agent/ccxt-mcp && exec node dist/index.js'\n\ncodex mcp add trading-intel \\\n  --env AUDIT_DATA_DIR=/ABS/PATH/codex-binance-agent/state/audit -- \\\n  bash -lc 'cd /ABS/PATH/codex-binance-agent/audit-system && exec node dist/mcp/index.js'\n```\n\n检查配置：\n\n```bash\ncodex mcp list\ncodex mcp get ccxt\ncodex mcp get trading-intel\n```\n\n注册后重新启动 Codex 会话。在 Codex TUI 中输入 `/mcp`，应能看到：\n\n- `ccxt`：市场、账户和交易工具。\n- `trading-intel`：本地审计分析、CoinGecko 和 DefiLlama 只读工具。\n\nCodex 也支持在 `~/.codex/config.toml` 或项目的 `.codex/config.toml` 中直接配置\nMCP；详见 [Codex MCP 文档](https://developers.openai.com/codex/mcp)。\n\n### 手工测试 MCP\n\n下面的服务使用 stdio，启动后没有普通终端输出并持续等待输入是正常现象；\n按 `Ctrl+C` 退出：\n\n```bash\ncd ccxt-mcp\nnpm start\n```\n\n开发模式：\n\n```bash\ncd ccxt-mcp\nnpm run dev\n```\n\n## 使用 Codex CLI 炒币\n\n必须从项目目录启动 Codex，使其读取根目录的 `AGENTS.md`、策略文件和项目本地\nskills：\n\n```bash\ncd /path/to/codex-binance-agent\ncodex\n```\n\n推荐先执行只读检查：\n\n```text\n使用 ccxt MCP 调用 ccxt_get_config，确认 exchange、defaultType、\n凭据状态、代理状态、CCXT_ENABLE_TRADING 和 CCXT_DRY_RUN。不要下单。\n```\n\n确认结果中 `enableTrading=false`、`dryRun=true` 后，再运行策略。\n\n### V1：单轮超级短线扫描\n\n在 Codex 中输入：\n\n```text\n$trading-v1 按 V1 运行一轮完整交易流程。当前只允许 dry-run，\n读取账户、持仓、普通订单、保护单和全市场行情，完成审计和最终总结，不要真实下单。\n```\n\n也可以直接从 shell 发起：\n\n```bash\ncodex -C /path/to/codex-binance-agent \\\n  '$trading-v1 按 V1 运行一轮完整 dry-run，禁止真实下单。'\n```\n\n### V2：连续决策循环\n\n```text\n$trading-v2 按 V2 启动连续交易流程，每 60 秒一轮。保持 dry-run，\n每轮完成账户对账、市场扫描、cooldown 检查、审计和总结，直到我要求停止。\n```\n\nV2 是当前 Codex 会话内的连续流程。不要用无人值守脚本、cron 或后台 runner\n代替 Codex 做交易决策。\n\n### V3：自由裁量交易\n\n```text\n$trading-v3 按 V3 运行一轮自由裁量交易流程。保持 dry-run，\n先完成账户级组合判断和必要研究，再决定是否交易，并写入完整审计。\n```\n\nV3 允许 Codex 使用脚本、公开网页和外部数据辅助研究，但最终账户动作必须由当前\nCodex 会话判断，并通过已验证的交易工具执行和复核。\n\n### 三种策略的区别\n\n| 策略 | 适用方式 | 核心特点 |\n| --- | --- | --- |\n| V1 | 单轮调用 | 全市场超级短线扫描，多候选和受保护执行。 |\n| V2 | 当前会话连续运行 | 默认每 60 秒一轮，包含 cooldown 和更严格的执行质量控制。 |\n| V3 | 单轮自由裁量 | 允许自由研究和脚本辅助，先做账户级组合判断。 |\n\n每次策略运行都必须重新读取对应的 `V*.txt`。策略阈值、风险和交易授权以该文件为准，\n执行顺序和审计纪律以对应 `.cursor/skills/trading-v*/SKILL.md` 为准。\n\n## 启用真实交易\n\n只有完成 dry-run、测试环境验证、API 权限检查和出口 IP 检查后，才考虑修改：\n\n```dotenv\nCCXT_ENABLE_TRADING=true\nCCXT_DRY_RUN=false\n```\n\n重新启动 Codex，然后先要求它调用 `ccxt_get_config`。只有返回结果明确显示\n`enableTrading=true` 且 `dryRun=false`，执行工具才会发送真实交易请求。\n\n真实交易提示词应明确策略版本和范围，例如：\n\n```text\n$trading-v1 按 V1 运行一轮。先确认交易开关、账户、持仓、普通订单和保护单；\n严格按 V1.txt 风控自主判断。只有所有门禁通过时才允许真实执行，\n执行后立即复核持仓、成交和止盈止损，并完成审计总结。\n```\n\n不要仅凭“已调用下单工具”判断交易成功。必须在动作后重新读取：\n\n- 账户余额和保证金。\n- 实际 positions。\n- 普通未成交订单。\n- 条件单和止盈止损保护单。\n- 最近成交、订单 ID、成交数量和均价。\n\n## 审计和复盘界面\n\n交易 skill 会把审计数据写入 `state/audit/`。启动本地复盘界面：\n\n```bash\ncd audit-system\nnpm run build\nAUDIT_DATA_DIR=../state/audit AUDIT_PORT=4177 npm start\n```\n\n浏览器打开：\n\n```text\nhttp://127.0.0.1:4177\n```\n\n常用审计命令：\n\n```bash\ncd audit-system\n\n# 列出交易轮次\nAUDIT_DATA_DIR=../state/audit npm run audit -- cycles\n\n# 校验指定轮次的 hash chain\nAUDIT_DATA_DIR=../state/audit npm run audit -- verify <cycle_id>\n\n# 列出当前 cooldown\nAUDIT_DATA_DIR=../state/audit npm run audit -- cooldowns list\n```\n\n审计系统本身不会下单、撤单、改仓、转账或提现。\n\n## Docker 运行 ccxt-mcp\n\n官方 Registry 名称：`io.github.lucyfox199818-collab/ccxt-mcp`\n\n无需本地构建，直接使用公开 GHCR 镜像：\n\n```bash\ndocker run --rm -i \\\n  -e CCXT_ENABLE_TRADING=false \\\n  -e CCXT_DRY_RUN=true \\\n  ghcr.io/lucyfox199818-collab/ccxt-mcp:0.1.0\n```\n\n注册到 Codex：\n\n```bash\ncodex mcp add ccxt-container \\\n  --env CCXT_ENABLE_TRADING=false \\\n  --env CCXT_DRY_RUN=true -- \\\n  docker run --rm -i \\\n  -e CCXT_ENABLE_TRADING \\\n  -e CCXT_DRY_RUN \\\n  ghcr.io/lucyfox199818-collab/ccxt-mcp:0.1.0\n```\n\n也可以从源码构建：\n\n```bash\ncd ccxt-mcp\ndocker build -t ccxt-mcp:local .\ndocker run --rm -i --env-file .env ccxt-mcp:local\n```\n\n使用 Docker 注册 MCP：\n\n```bash\ncodex mcp add ccxt-docker -- \\\n  docker run --rm -i \\\n  --env-file /ABS/PATH/codex-binance-agent/ccxt-mcp/.env \\\n  ccxt-mcp:local\n```\n\n## 开发和验证\n\n```bash\ncd ccxt-mcp\nnpm test\nnpm run typecheck\nnpm run build\n\ncd ../audit-system\nnpm test\nnpm run typecheck\nnpm run build\n```\n\n更详细的组件文档：\n\n- [`ccxt-mcp/README.md`](ccxt-mcp/README.md)\n- [`audit-system/README.md`](audit-system/README.md)\n- [`CONTRIBUTING.md`](CONTRIBUTING.md)\n\n## 常见问题\n\n### Codex 看不到 MCP\n\n```bash\ncodex mcp list\ncodex mcp get ccxt\n```\n\n确认两个子项目都已构建且 `dist/` 存在，然后重启 Codex。在 TUI 中使用 `/mcp`\n检查初始化错误。\n\n### MCP 启动后一直没有输出\n\n这是 stdio MCP 的正常行为。它正在等待客户端协议消息，不是 HTTP 服务。\n\n### 能读取行情但不能读取余额\n\n公共行情不需要 API key；余额、持仓、订单和成交历史需要正确的 API 凭据和权限。\n\n### 下单工具返回 dry-run\n\n这是默认安全行为。检查 `ccxt_get_config` 的 `enableTrading` 和 `dryRun`，不要在未完成\n测试和风险检查时关闭 dry-run。\n\n### 修改 `.env` 后没有生效\n\nMCP 进程启动时读取环境变量。退出并重新启动 Codex 会话，让 Codex 重启 MCP 服务。\n\n## 联系方式\n\n- 微信：`mypcwza`\n- Telegram：`mypcwza`\n",
  "bytes": 7993,
  "sha": "1d21dd2a73acbf923144e3df242626180cb6feca718bdc4a139818e6b634fab5",
  "repo_slug": "lucyfox199818-collab/codex-binance-agent",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lucyfox199818_collab_ccxt_mcp_f5207360/readme"
}