OctoBot 2.1.1 配置参数详解

目标：把 OctoBot 2.1.1 的全部配置体系讲透——三层配置文件（全局 config.json、Profile 的 profile.json 与 tentacles_config.json、策略级 specific_config）+ 日志配置 + 启动环境变量的字段含义、默认值与修改方式。本文所有配置文件内容与切换实验均在 Ubuntu 22.04 + OctoBot 2.1.1 环境实测采集（2026-10-24），回显逐行照抄。

一、环境信息

操作系统：Ubuntu 22.04.4 LTS（x86_64）
OctoBot：2.1.1 官方稳定版（发行包 drakkarsoftware/octobot:2.1.1）
部署形态：官方 Docker 发行包部署（部署过程见《OctoBot Docker Compose 部署指南》），四个数据目录持久化到宿主机 /opt/octobot/（本文以该路径为准）
数据目录结构（首次启动后实测 ls -R 采集）：

user/
├── BrowsingDataProvider_data.json      # Web 界面浏览状态缓存
├── config.json                         # 全局配置（本文主角之一）
├── data/                               # 行情数据缓存（live/）
├── logging_config.ini                  # 日志配置（Python logging 格式）
├── profiles/                           # 18 个官方 Profile + 用户自建 Profile
│   ├── non-trading/                    # 默认 Profile
│   │   ├── profile.json                # Profile 元数据 + 交易参数
│   │   ├── tentacles_config.json       # 插件激活表（本文主角之一）
│   │   ├── specific_config/            # 策略/交易模式级参数
│   │   │   └── BlankStrategyEvaluator.json
│   │   └── default_profile.png         # Profile 头像
│   ├── daily_trading/
│   └── …（共 18 个）
└── reference_tentacles_config/         # 官方参考配置（重置用）

二、前置条件

已按部署篇完成 OctoBot 2.1.1 部署并能访问 Web 界面（http://<服务器IP>:5001）；
已完成首次启动（tentacles 安装与 Profile 同步），user/ 目录下存在 config.json 与 profiles/；
修改配置前建议备份：cp -a user/config.json user/config.json.bak；
了解修改生效规则：OctoBot 仅在启动时装载配置，任何文件级修改都需要重启服务（部署篇的 docker compose restart octobot，实测见 FAQ）。

三、参数查看与修改方式

OctoBot 提供两条等价的配置修改路径，实测中二者写的是同一组文件：

方式	入口	生效方式	适用场景
Web 界面	Profile 页（参数面板）、Accounts 页（交易所）、Advanced 页（config.json 直接编辑）	部分界面项即时保存，交易相关改动会提示重启	日常调整
直接编辑文件	`user/config.json`、`user/profiles/<名称>/profile.json` 等	保存后必须重启服务	批量修改、脚本化管理

⚠️ 注意：Web 界面保存交易所 API Key 时会做加密处理；手工编辑 config.json 明文填 Key 也可以运行，但官方提供了专门的加密工具（CLI OctoBot --encrypter，见命令详解篇）。任何方式的修改在重启前都不会生效，实测验证：把 "profile" 字段从 "default" 改为 "daily_trading" 并重启后，启动日志出现 Using DailyTrading profile.；若不重启则维持原 Profile。

四、参数总览：三层配置地图

层级	文件	管辖范围	典型字段
全局层	`user/config.json`	跨 Profile 的基础设施：交易所、Web、通知、社区、当前 Profile 指向	`exchanges`、`services`、`notification`、`profile`
Profile 层	`user/profiles/<名称>/profile.json`	单套策略行为：交易标的、风险、模拟器资金、实盘开关	`config.crypto-currencies`、`config.trading`、`config.trader(-simulator)`
插件激活层	同目录 `tentacles_config.json`	该 Profile 启用哪些评估器/策略/交易模式/交易所	`tentacle_activation.*` 布尔表
插件参数层	同目录 `specific_config/*.json`	单个交易模式或策略的细粒度参数	`DailyTradingMode.json`、`BlankStrategyEvaluator.json`

关键解读：切换 Profile（config.json 的 profile 字段）会同时切换第 2/3/4 层，这就是"一套 Profile 一套策略"的实现机制；交易所与 Web 这类基础设施不受 Profile 切换影响，放在全局层。

五、全局配置 user/config.json 逐项详解

首次启动（接受条款后）实测的完整文件（路径 user/config.json）：

{
    "accepted_terms": true,
    "backtesting": {
        "files": []
    },
    "community": {
        "local_data_identifier": "089ff082b20aa81395b7e5ce0f83ce20d133837d480eb682c4348406864f2d7c",
        "supabase.auth.token": ""
    },
    "exchanges": {
        "binance": {
            "api-key": "your-api-key-here",
            "api-password": "your-api-password-here",
            "api-secret": "your-api-secret-here",
            "enabled": true,
            "exchange-type": "spot"
        }
    },
    "notification": {
        "global-info": true,
        "notification-type": [
            "web"
        ],
        "other": true,
        "price-alerts": true,
        "trades": true,
        "trading-script-alerts": true
    },
    "profile": "daily_trading",
    "services": {
        "web": {
            "auto-open-in-web-browser": true,
            "password": "",
            "require-password": false
        }
    }
}

💡 说明："profile" 字段在全新安装时为 "default"；本文为演示 Profile 切换实验已将其改为 "daily_trading"（见第八章实验）。接受服务条款前首次访问时，accepted_terms 为 false，Web 访问会被重定向到 /terms 页面。

逐项说明：

字段	默认值	含义与修改建议
`accepted_terms`	首次访问为 `false`	服务条款确认标记；Web 界面点同意后自动置 `true`
`backtesting.files`	`[]`	回测数据文件列表；由 Web 界面 Data Collector 采集后自动填充，命令行 `-bf` 可临时指定
`community.local_data_identifier`	启动时生成的 64 位十六进制	本机实例标识（bot_id 来源之一），勿手工修改
`community."supabase.auth.token"`	`""`	OctoBot 社区账号登录令牌；Web 界面 Community 页登录后自动写入
`exchanges.<id>.api-key`	占位串 `your-api-key-here`	交易所 API Key；模拟器形态可保持占位值不接真实 Key
`exchanges.<id>.api-secret`	占位串	交易所 API 私钥；Web 界面保存时自动加密存储
`exchanges.<id>.api-password`	占位串	部分交易所（如 OKX）需要的口令短语，其他交易所可留占位
`exchanges.<id>.enabled`	`true`	是否启用该交易所连接
`exchanges.<id>.exchange-type`	`spot`	市场类型：`spot`（现货）；合约需对应交易所 tentacle 支持
`notification.notification-type`	`["web"]`	通知通道列表；可加 `"telegram"` 等（需先激活对应 Services tentacle 并配好凭据）
`notification.trades`	`true`	成交通知
`notification.price-alerts`	`true`	价格提醒通知
`notification.global-info` / `other`	`true`	全局信息/其他事件通知开关
`profile`	`"default"`	当前激活 Profile 的目录名；切换即切换整套策略（需重启）
`services.web.require-password`	`false`	Web 界面是否要求登录密码；公网部署建议 `true`
`services.web.password`	`""`	Web 登录密码明文（界面保存时写入）；与上一项配合使用
`services.web.auto-open-in-web-browser`	`true`	有桌面环境时自动打开浏览器；无头服务器上无实际作用，可不管

⚠️ 注意：exchanges 中即使保持 your-api-key-here 占位值，OctoBot 也会以未认证方式连接该交易所公开行情（实测启动日志：Creating unauthenticated binance SPOT exchange with ccxt in version 4.5.44），这正是不接真实 Key 跑模拟器的原理。接入真实 Key 属实盘范畴，务必先在模拟器验证策略。

六、Profile 层配置 profile.json 详解

6.1 文件结构总览

每个 Profile 一个目录，profile.json 由 profile（元数据）与 config（交易参数）两块组成。实测 user/profiles/non-trading/profile.json 完整内容：

{
    "config": {
        "crypto-currencies": {
            "Bitcoin": {
                "enabled": true,
                "pairs": [
                    "BTC/USDT"
                ]
            }
        },
        "distribution": "default",
        "exchanges": {
            "binance": {
                "enabled": true,
                "exchange-type": "spot"
            }
        },
        "trader": {
            "enabled": false,
            "load-trade-history": true
        },
        "trader-simulator": {
            "enabled": true,
            "fees": {
                "maker": 0.1,
                "taker": 0.1
            },
            "starting-portfolio": {
                "USDT": 10000
            }
        },
        "trading": {
            "reference-market": "USDT",
            "risk": 0.5
        }
    },
    "profile": {
        "auto_update": false,
        "avatar": "default_profile.png",
        "complexity": 1,
        "description": "Non-Trading is a profile that does not trade. It will not create any order. Use this profile to run OctoBot without creating any order.",
        "extra_backtesting_time_frames": [],
        "hidden": false,
        "id": "default",
        "imported": false,
        "name": "Non-Trading",
        "origin_url": null,
        "read_only": true,
        "risk": 1,
        "slug": "",
        "type": "live"
    }
}

6.2 config 块（交易参数）逐项说明

字段	实测默认值	含义
`crypto-currencies.<币种>.pairs`	`["BTC/USDT"]`	该币种要交易的交易对列表；交易所 ID 需支持该对
`crypto-currencies.<币种>.enabled`	`true`	币种级开关
`distribution`	`"default"`	资金分配策略标识（组合层参数，默认即可）
`exchanges.<id>.enabled`	`true`	Profile 级交易所启用；与全局层的区别：这里只决定"本 Profile 是否用到它"
`trader.enabled`	`false`	真实交易开关；`false` + 模拟器开启 = 模拟盘形态。置 `true` 前必须完成 API Key 配置与风险评估
`trader.load-trade-history`	`true`	启动时加载历史成交
`trader-simulator.enabled`	`true`	模拟交易器开关（与 `trader.enabled` 组合决定运行形态）
`trader-simulator.fees.maker/taker`	`0.1` / `0.1`	模拟撮合手续费率（百分比，0.1 = 0.1%）；可按目标交易所费率调整
`trader-simulator.starting-portfolio`	`{"USDT": 10000}`	模拟器初始资金；如 `{"BTC": 10, "USDT": 1000}`（DailyTrading Profile 实测默认值）
`trading.reference-market`	`"USDT"`	参考计价市场，收益统计按它计算
`trading.risk`	`0.5`	风险系数（0~~1），影响仓位大小；Profile 元数据的 `risk`（1~~10 档）是界面展示档位，二者独立

💡 技术拓展：trader.enabled 与 trader-simulator.enabled 的组合即交易机器人常见的三种运行形态——| trader | trader-simulator | 形态 | 资金来源 |；| false | true | 模拟盘（官方默认） | 虚拟资金 |；| true | 任意 | 实盘 | 交易所真实账户 |；| false | false | 只读分析 | 无下单能力 |。OctoBot 通过这两个布尔值而非独立"模式参数"实现形态切换，优点是模拟与实盘共用同一套策略配置，切换成本低；缺点是实盘开关就在配置文件里，需通过界面二次确认来防误触。

6.3 profile 块（元数据）逐项说明

字段	实测值（Non-Trading）	含义
`id`	`"default"`	Profile 内部标识（= 目录名；DailyTrading Profile 实测为 `"daily_trading"`）
`name`	`"Non-Trading"`	界面显示名
`description`	英文一句话	界面展示的策略说明
`complexity`	`1`	复杂度星级（界面筛选用）
`risk`	`1`	风险档位 1~~10（与 `config.trading.risk` 的 0~~1 系数是两回事）
`type`	`"live"`	Profile 类型：`live` 实时交易 / 回测专用等
`read_only`	`true`	官方 Profile 为只读，界面修改参数时会先复制出新 Profile；自建 Profile 为 `false`
`hidden` / `auto_update` / `imported` / `origin_url` / `slug` / `avatar` / `extra_backtesting_time_frames`	`false`/`false`/`false`/`null`/`""`/`default_profile.png`/`[]`	展示与同步元数据：是否隐藏、是否跟随官方更新、是否导入、来源 URL、短链、头像、回测附加时间框架

七、插件激活层 tentacles_config.json 详解

7.1 文件结构

实测文件由三部分组成（节选自 user/profiles/non-trading/tentacles_config.json）：

{
    "installation_context": {
        "octobot_version": "2.1.1"
    },
    "registered_tentacles": {
        "OctoBot-Default-Tentacles": "https://tentacles.octobot.online/officials/packages/full/base/2.1.1/any_platform.zip"
    },
    "tentacle_activation": {
        "Evaluator": {
            "BlankStrategyEvaluator": true,
            "RSIMomentumEvaluator": false,
            "…": "（其余略，全量布尔表）"
        },
        "Trading": {
            "BlankTradingMode": true,
            "Binance": true,
            "BinanceCCXTWebsocketConnector": true,
            "…": "（其余略）"
        }
    }
}

字段	含义	修改方式
`installation_context.octobot_version`	安装该插件包时的 OctoBot 版本	升级后由安装器维护
`registered_tentacles`	已注册插件包及其下载地址	命令行 `OctoBot tentacles -l <URL> -i` 安装新包时写入
`tentacle_activation.<类型>.<名称>`	该 Profile 下每个 tentacle 的启用布尔表	Web 界面 Profile 页的配置面板逐项勾选，或直接编辑后重启

7.2 Profile 间激活差异（实测对照）

同一份插件包在不同 Profile 下激活面不同，实测两个官方 Profile 的关键差异：

tentacle 组	Non-Trading（默认）	DailyTrading
Evaluator.TA（指标）	全部 `false`（不用指标）	`RSIMomentumEvaluator`、`DoubleMovingAverageTrendEvaluator` 等激活
Evaluator.Strategies（策略）	`BlankStrategyEvaluator: true`	`SimpleStrategyEvaluator: true`
Trading.Mode（交易模式）	`BlankTradingMode: true`（不下单）	`DailyTradingMode: true`
交易模式效果（实测启动日志）	`Starting OctoBot with simulated trader on binance[spot] trading BTC/USDT with BlankTradingMode`	`… with DailyTradingMode`

关键解读：tentacle_activation 决定"能力池"，profile.json 决定"怎么用"，specific_config 决定"用多细"。三层的组合构成一个 Profile 的完整行为定义。

八、插件参数层 specific_config 详解

specific_config/ 目录按 tentacle 名称存放 JSON 参数文件。实测两个代表性文件：

8.1 交易模式参数 DailyTradingMode.json（实测完整内容）

{
    "close_to_current_price_difference": 0.005,
    "default_config": [
        "SimpleStrategyEvaluator"
    ],
    "required_strategies": [
        "SimpleStrategyEvaluator",
        "TechnicalAnalysisStrategyEvaluator"
    ],
    "required_strategies_min_count": 1,
    "sell_with_maximum_size_orders": false,
    "buy_with_maximum_size_orders": false,
    "use_prices_close_to_current_price": false,
    "disable_buy_orders": false,
    "disable_sell_orders": false,
    "use_stop_orders": true
}

逐项说明：

字段	默认值	含义
`required_strategies`	`["SimpleStrategyEvaluator", "TechnicalAnalysisStrategyEvaluator"]`	该交易模式可搭配的策略评估器白名单
`required_strategies_min_count`	`1`	至少需启用几条策略才能运行
`default_config`	`["SimpleStrategyEvaluator"]`	默认启用的策略
`use_stop_orders`	`true`	是否生成止损单
`use_prices_close_to_current_price`	`false`	是否用接近现价的限价单挂单
`close_to_current_price_difference`	`0.005`	"接近现价"的偏离度（0.5%），上一项开启时生效
`buy_with_maximum_size_orders` / `sell_with_maximum_size_orders`	`false`	买入/卖出是否用最大仓单（一次性全仓进出）
`disable_buy_orders` / `disable_sell_orders`	`false`	只卖不买 / 只买不卖的单向模式开关

8.2 策略评估器参数 BlankStrategyEvaluator.json（实测完整内容）

{
  "required_time_frames" : ["1h"],
  "required_evaluators" : ["*"],
  "required_candles_count" : 200,
  "default_config" : []
}

逐项说明：required_time_frames（策略运行所需 K 线时间框架，默认 1h）；required_evaluators（依赖的指标评估器，* 表示接受任意组合）；required_candles_count（指标计算需要的最少 K 线数量，默认 200 根）；default_config（默认激活的子配置项）。

8.3 日志配置 logging_config.ini（实测完整内容）

首次启动生成于 user/logging_config.ini，采用 Python 标准 logging 配置格式：

[loggers]
keys=root

[handlers]
keys=consoleHandler,fileHandler

[formatters]
keys=consoleFormatter,fileFormatter

[logger_root]
level=DEBUG
handlers=consoleHandler,fileHandler

[handler_consoleHandler]
class=StreamHandler
level=INFO
formatter=consoleFormatter
args=(sys.stdout,)

[handler_fileHandler]
class=handlers.RotatingFileHandler
level=DEBUG
formatter=fileFormatter
args=('logs/OctoBot.log', 'a', 24000000, 20)

[formatter_consoleFormatter]
class=colorlog.ColoredFormatter
format=%(log_color)s %(asctime)s %(levelname)-8s %(name)-20s %(message)s

[formatter_fileFormatter]
format=%(asctime)-16s %(levelname)-6s %(name)-20s %(filename)-s:%(lineno)-8s %(message)s
datefmt=%Y-%m-%d %H:%M:%S

常用调整：[handler_fileHandler] 的 args=('logs/OctoBot.log', 'a', 24000000, 20) 中 24000000 为单文件字节上限（约 24 MB）、20 为滚动保留份数，日志盘紧张时调小；控制台级别 level=INFO 可改为 WARNING 减少输出。修改后重启生效。

九、生产配置模板

以"单服务器、模拟盘先行、后续小资金实盘、2 核 2 GB 内存"为目标场景的推荐配置（在默认文件基础上修改的关键项，其余保持默认）：

{
    "exchanges": {
        "binance": {
            "api-key": "your-api-key-here",
            "api-password": "your-api-password-here",
            "api-secret": "your-api-secret-here",
            "enabled": true,
            "exchange-type": "spot"
        }
    },
    "profile": "daily_trading",
    "services": {
        "web": {
            "auto-open-in-web-browser": false,
            "password": "q1w2e3r4",
            "require-password": true
        }
    }
}

配套 Profile（user/profiles/daily_trading/profile.json 的 config 块）推荐起步值：

{
    "trader": {
        "enabled": false,
        "load-trade-history": true
    },
    "trader-simulator": {
        "enabled": true,
        "fees": {
            "maker": 0.1,
            "taker": 0.1
        },
        "starting-portfolio": {
            "USDT": 10000
        }
    },
    "trading": {
        "reference-market": "USDT",
        "risk": 0.5
    }
}

要点解读：公网服务器必开 Web 密码（示例用固定测试口令 q1w2e3r4，生产请替换为自己的强口令并同样保管好）；trader.enabled 保持 false 直到模拟盘连续观察至少数周且 trader-simulator 的手续费率已改成目标交易所真实费率；风险系数 0.5 起步，验证后再调；2 GB 内存机器足够运行单实例（实测数百 MB 量级）。

十、常见问题（FAQ）

Q1：改了配置文件为什么没生效？ OctoBot 只在启动时装载配置。实测：config.json 的 "profile" 改为 "daily_trading" 后立即查看界面仍是 Non-Trading，重启服务后日志出现 Using DailyTrading profile.、交易模式变为 DailyTradingMode。重启命令见部署篇第八章。

Q2：Profile 切错了怎么恢复？ 把 "profile" 改回 "default"（或任意 Profile 目录名）重启即可；官方 Profile 目录都是只读（read_only: true），界面改参时它会先复制成用户副本，不会破坏原始定义。

Q3：模拟器初始资金能随便改吗？ 能。trader-simulator.starting-portfolio 改后重启生效，建议同时把 fees 调成目标交易所真实费率，收益统计才有参考意义。

Q4：Web 界面改的参数存在哪？存在 config.json 吗？ 分层存放：交易所/Web/通知等在 user/config.json；策略与交易模式参数在当前 Profile 的 specific_config/*.json；评估器与交易模式的启停在该 Profile 的 tentacles_config.json。找不到某参数落到哪，可改完后用 grep -r "<字段名>" user/ 定位。

Q5：tentacles_config.json 里的激活项太多，能手工清吗？ 不建议直接大改：未激活的 tentacle 只是不参与运行，不影响资源占用；手工删条目可能破坏安装器一致性。需要批量调整时用 Web 界面配置面板或 OctoBot tentacles -r 修复。

Q6：交易所 Key 明文写在 config.json 安全吗？ 文件级明文只建议在离线/私有环境使用；通过 Web 界面 Accounts 页录入的 Key 会加密存储。手工导入明文 Key 时官方提供 OctoBot --encrypter 工具生成密文（用法见命令详解篇）。

十一、参考链接

官方配置指南：https://www.octobot.cloud/en/guides/octobot-configuration
Profile 与策略文档：https://www.octobot.cloud/en/guides/strategies
GitHub 仓库（配置结构源码）：https://github.com/Drakkar-Software/OctoBot
本专栏相关篇目：《OctoBot 2.1.1 介绍与选型指南》、《OctoBot Docker Compose 部署指南》、《OctoBot 2.1.1 常用 CLI 命令与工具详解》