Ganglion — Operator's Manual

Ganglion is a domain-specific execution engine for Bittensor subnet mining. It provides a pipeline framework for orchestrating autonomous mining agents that search for optimal model configurations. It exposes a CLI, an HTTP bridge API, and a Python library. Ganglion is search infrastructure — it doesn't know what a good model looks like, it knows how to search for one.

Quick Reference

CODEBLOCK0

Mode Detection

Ganglion supports two modes. Always check which mode applies before running commands.

- Local mode: No GANGLION_URL set, or GANGLION_PROJECT is set. Use ganglion <command> <project_dir> directly.
Remote mode: GANGLION_URL is set. Use curl against the HTTP bridge.

CODEBLOCK1

Response Format

All HTTP bridge endpoints (except health probes) return responses in a standard envelope:

- Success: {"data": <payload>} — use jq .data to extract
Error: INLINECODE7

Health probes (/healthz, /readyz) return raw JSON without the envelope.

Interactive API docs: $GANGLION_URL/v1/docs (Swagger UI).

Note: Unversioned routes (e.g. /status) still work but are deprecated. Always use /v1/.

How to Run

Prerequisites: Python >= 3.11, OPENAI_API_KEY set (used by the LLM runtime).

Install: INLINECODE14

Scaffold a project:

ganglion init ./my-subnet --subnet sn9 --netuid 9

This creates config.py, tools/, agents/, and skill/ in the target directory.

Start in local mode:
CODEBLOCK3

Start in remote mode:
CODEBLOCK4

The project directory must contain a config.py that defines subnet_config (SubnetConfig) and pipeline (PipelineDef). See {baseDir}/references/configuration.md for full config details.

Key Features

Observe State

Query the current framework state — registered tools, agents, pipeline definition, knowledge, metrics, and run history. Local mode uses CLI commands; remote mode uses GET endpoints.

Full reference: INLINECODE23

Execute Pipelines

Run the full pipeline or a single stage. The orchestrator executes stages in dependency order, applies retry policies, injects accumulated knowledge into agent prompts, and records outcomes.

CODEBLOCK5

Mutate at Runtime (Remote Only)

Register new tools, agents, and components; patch the pipeline; swap retry policies; update prompts. All mutations are validated, audited, and reversible.

CODEBLOCK6

Pipeline operations: add_stage, remove_stage, update_stage. See {baseDir}/references/commands.md for all mutation endpoints.

Knowledge Store

Cross-run strategic memory that compounds over time. Records patterns (what worked) and antipatterns (what failed), then automatically injects relevant history into agent prompts. Knowledge is queried by capability and filtered by bot_id for multi-bot setups.

CODEBLOCK7

Rollback

Undo any mutation. Every mutation is recorded in an audit log with rollback data.

CODEBLOCK8

Multi-Bot Workflows

Multiple OpenClaw sessions share a knowledge pool via --bot-id. Each bot's discoveries flow into the shared pool. Cooperation emerges from shared knowledge, not explicit coordination.

CODEBLOCK9

MCP Integration

Connect to external MCP servers to add tools to the agent's repertoire at runtime. Tools from MCP servers appear as regular Ganglion tools with a prefix.

CODEBLOCK10

Common Workflows

See {baseDir}/examples/common-workflows.md for full step-by-step guides.

1. First run: ganglion init → edit config.py → INLINECODE32
Iterative mining: check status → review knowledge → run pipeline → check metrics → repeat
Dynamic mutation: observe tools/agents → register new tool via API → patch pipeline → run
Multi-bot setup: start multiple servers with different --bot-id values on the same project
MCP integration: connect external tool servers → tools appear in registry → agents can use them

When Things Go Wrong

Symptom	Likely Cause	Fix
INLINECODE34	Wrong project path	Verify path contains INLINECODE35
INLINECODE36 errors

Full troubleshooting: INLINECODE41

Retry Policies

Four built-in policies control how stages retry on failure:

- NoRetry — single attempt
FixedRetry — retry N times (default: 3)
EscalatingRetry — increase temperature per attempt, optional stall detection
ModelEscalationRetry — climb a model cost ladder (cheap → expensive)

Three presets: SN50_PRESET (escalating + stall detection), SIMPLE_PRESET (fixed), AGGRESSIVE_PRESET (model escalation).

Additional Resources

- Full CLI & API reference: INLINECODE45
Configuration guide: INLINECODE46
Operational procedures: INLINECODE47
Troubleshooting: INLINECODE48
Workflow examples: INLINECODE49
Sample API requests: INLINECODE50
Health check script: INLINECODE51

Ganglion — 操作手册

Ganglion 是一个面向 Bittensor 子网挖矿的领域特定执行引擎。它提供了一个管道框架，用于编排搜索最优模型配置的自主挖矿代理。它提供了 CLI、HTTP 桥接 API 和 Python 库。Ganglion 是搜索基础设施——它不知道什么样的模型是好的，它知道如何搜索模型。

快速参考

bash

搭建新项目

ganglion init ./my-subnet --subnet sn9 --netuid 9

检查状态（本地模式）

ganglion status ./my-subnet ganglion tools ./my-subnet ganglion agents ./my-subnet ganglion knowledge ./my-subnet --capability training --max-entries 10 ganglion pipeline ./my-subnet

运行（本地模式）

ganglion run ./my-subnet ganglion run ./my-subnet --stage plan ganglion run ./my-subnet --overrides {target_metric:accuracy}

启动 HTTP 桥接（远程模式）

ganglion serve ./my-subnet --bot-id alpha --port 8899

检查状态（远程模式）

curl -s $GANGLION_URL/v1/status | jq .data

模式检测

Ganglion 支持两种模式。在运行命令前务必检查当前适用的模式。

- 本地模式：未设置 GANGLIONURL，或设置了 GANGLIONPROJECT。直接使用 ganglion dir>。
远程模式：设置了 GANGLIONURL。使用 curl 访问 HTTP 桥接。

bash
if [ -n $GANGLIONPROJECT ] || [ -z $GANGLIONURL ]; then
echo local
else
echo remote
fi

响应格式

所有 HTTP 桥接端点（健康检查除外）返回标准信封格式的响应：

- 成功：{data: } — 使用 jq .data 提取
错误：{detail: {error: {code: ERROR_CODE, message: ...}}}

健康检查端点（/healthz、/readyz）返回原始 JSON，不包含信封。

交互式 API 文档：$GANGLION_URL/v1/docs（Swagger UI）。

注意： 无版本号的路由（例如 /status）仍然可用但已弃用。请始终使用 /v1/。

如何运行

前置条件： Python >= 3.11，已设置 OPENAIAPIKEY（由 LLM 运行时使用）。

安装： pip install ganglion

搭建项目：
bash
ganglion init ./my-subnet --subnet sn9 --netuid 9

这会在目标目录中创建 config.py、tools/、agents/ 和 skill/。

以本地模式启动：
bash
export GANGLION_PROJECT=./my-subnet
ganglion status $GANGLION_PROJECT

以远程模式启动：
bash
ganglion serve ./my-subnet --bot-id alpha --port 8899
export GANGLION_URL=http://127.0.0.1:8899

项目目录必须包含一个 config.py，其中定义了 subnet_config（SubnetConfig）和 pipeline（PipelineDef）。完整配置详情请参见 {baseDir}/references/configuration.md。

主要功能

观察状态

查询当前框架状态——已注册的工具、代理、管道定义、知识、指标和运行历史。本地模式使用 CLI 命令；远程模式使用 GET 端点。

完整参考：{baseDir}/references/commands.md

执行管道

运行完整管道或单个阶段。编排器按依赖顺序执行阶段，应用重试策略，将累积的知识注入代理提示，并记录结果。

bash

本地

ganglion run ./my-subnet
ganglion run ./my-subnet --stage plan

远程

curl -s -X POST $GANGLION_URL/v1/run/pipeline -H Content-Type: application/json -d {} | jq .data curl -s -X POST $GANGLION_URL/v1/run/stage/plan -H Content-Type: application/json -d {} | jq .data

运行时变更（仅远程）

注册新工具、代理和组件；修补管道；交换重试策略；更新提示。所有变更都经过验证、审计且可逆。

bash

注册工具

curl -s -X POST $GANGLION_URL/v1/tools -H Content-Type: application/json \
-d {name:my_tool,code:

,category:training} | jq .data
修补管道
curl -s -X PATCH $GANGLION_URL/v1/pipeline -H Content-Type: application/json \
  -d {operations:[{op:addstage,stage:{name:validate,agent:Validator,dependson:[train]}}]} | jq .data
管道操作：addstage、removestage、update_stage。所有变更端点请参见 {baseDir}/references/commands.md。
知识存储
跨运行的战略性记忆，随时间累积。记录模式（有效的方法）和反模式（失败的方法），然后自动将相关历史注入代理提示。按能力查询知识，并通过 bot_id 过滤以支持多机器人设置。
bash

本地


ganglion knowledge ./my-subnet --bot-id alpha --capability training
远程
curl -s $GANGLIONURL/v1/knowledge?capability=training&maxentries=10 | jq
回滚
撤销任何变更。每次变更都记录在审计日志中，并附带回滚数据。
bash

curl -s -X POST $GANGLION_URL/v1/rollback/last | jq

curl -s -X POST $GANGLION_URL/v1/rollback/0 | jq    # 撤销所有变更
多机器人工作流
多个 OpenClaw 会话通过 --bot-id 共享知识池。每个机器人的发现流入共享池。协作源于共享知识，而非显式协调。
bash

两个本地会话


ganglion run ./my-subnet --bot-id alpha

ganglion run ./my-subnet --bot-id beta
两个远程服务器
ganglion serve ./my-subnet --bot-id alpha --port 8899
ganglion serve ./my-subnet --bot-id beta  --port 8900
MCP 集成
连接外部 MCP 服务器，在运行时为代理添加工具。
来自 MCP 服务器的工具会以带前缀的形式显示为常规 Ganglion 工具。
bash

静态：添加到 config.py


from ganglion.mcp.config import MCPClientConfig


mcpclients = [MCPClientConfig(name=weather, transport=stdio, command=[python, -m, weatherserver])]

动态：通过 API 在运行时添加
curl -s -X POST $GANGLION_URL/v1/mcp/servers -H Content-Type: application/json \
  -d {name:weather,transport:stdio,command:[python,-m,weather_server]} | jq .data
检查已连接的 MCP 服务器
curl -s $GANGLION_URL/v1/mcp | jq .data
断开连接
curl -s -X DELETE $GANGLION_URL/v1/mcp/servers/weather | jq .data
将 Ganglion 工具暴露为 MCP 服务器（用于 Claude Desktop 等）
ganglion mcp-serve ./my-subnet --transport stdio
常见工作流
完整的分步指南请参见 {baseDir}/examples/common-workflows.md。
1. 首次运行：ganglion init → 编辑 config.py → ganglion run
迭代挖矿：检查状态 → 查看知识 → 运行管道 → 检查指标 → 重复
动态变更：观察工具/代理 → 通过 API 注册新工具 → 修补管道 → 运行
多机器人设置：在同一个项目上使用不同的 --bot-id 值启动多个服务器
MCP 集成：连接外部工具服务器 → 工具出现在注册表中 → 代理可以使用它们
问题排查
症状 可能原因 解决方法
FileNotFoundError: No config.py 项目路径错误 确认路径包含 config.py
OPENAIAPIKEY 错误
 API 密钥缺失或无效 | export OPENAIAPIKEY=sk-... |
| ConcurrentMutationError | 在管道运行时

症状	可能原因	解决方法
FileNotFoundError: No config.py	项目路径错误	确认路径包含 config.py
OPENAIAPIKEY 错误

代码库指南

代码库指南

Ganglion — Operator's Manual

Quick Reference

Mode Detection

Response Format

How to Run

Key Features

Observe State

Execute Pipelines

Mutate at Runtime (Remote Only)

Knowledge Store

Rollback

Multi-Bot Workflows

MCP Integration

Common Workflows

When Things Go Wrong

Retry Policies

Additional Resources

Ganglion — 操作手册

快速参考

搭建新项目

检查状态（本地模式）

运行（本地模式）

启动 HTTP 桥接（远程模式）

检查状态（远程模式）

模式检测

响应格式

如何运行

主要功能

观察状态

执行管道

本地

远程

运行时变更（仅远程）

注册工具

修补管道

知识存储

本地

远程

回滚

多机器人工作流

两个本地会话

两个远程服务器

MCP 集成

静态：添加到 config.py

from ganglion.mcp.config import MCPClientConfig

mcpclients = [MCPClientConfig(name=weather, transport=stdio, command=[python, -m, weatherserver])]

动态：通过 API 在运行时添加

检查已连接的 MCP 服务器

断开连接

将 Ganglion 工具暴露为 MCP 服务器（用于 Claude Desktop 等）

常见工作流

问题排查

标签

通过对话安装

方式一：安装 SkillHub 和技能

方式二：设置 SkillHub 为优先技能安装源

通过命令行安装

下载

相关推荐

self-improvement

self-improvement

self-improvement

self-improvement