Octop AI 助手官网：腾讯云开源项目入口、API 与环境配置

Octop AI 助手是腾讯云开源的自托管、多用户、多智能体平台。查看项目应进入 TencentCloud/Octop 官方仓库；调用 API 或打开管理界面，则需要先运行自己的 Octop 实例。本机默认服务地址为 http://127.0.0.1:8088，API 路径统一以 /api 开头。

Octop 官方项目与文档入口

官网、代码仓库和实例 API 的用途不同。官网用于了解产品，GitHub 仓库提供源码与版本文档，本地地址才是部署完成后的实际操作入口。

Octop 官方网站：
https://octop.cloud

腾讯云官方开源仓库：
https://github.com/TencentCloud/Octop

官方配置文档：
https://github.com/TencentCloud/Octop/blob/main/docs/configuration.md

官方 API 文档：
https://github.com/TencentCloud/Octop/blob/main/docs/api.md

本机默认管理界面：
http://127.0.0.1:8088

Octop 是自托管项目，因此不存在一个供所有部署共用的云端 API 地址。服务器域名、端口、账号和数据均由部署者管理。

API 地址与认证方式

官方 API 参考说明，所有路由均挂载在 /api 下。默认本机部署的 API 基础地址可写为 http://127.0.0.1:8088/api。健康检查、首次设置、登录和 OpenAPI 模式等少数端点可公开访问，其余接口通常需要 JWT。

# 检查服务状态
curl http://127.0.0.1:8088/api/health

# 登录并获取访问令牌
curl -X POST http://127.0.0.1:8088/api/auth/login 
  -H "Content-Type: application/json" 
  -d '{"username":"YOUR_USER","password":"YOUR_PASSWORD"}'

# 调用受保护接口
curl http://127.0.0.1:8088/api/auth/me 
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

访问令牌默认有效期为 86400 秒，可通过配置调整。轮换 JWT 密钥会立即使已签发令牌失效；连续登录失败还可能触发锁定，因此程序不应通过高频重试规避认证错误。

如何开启交互式 API 文档

交互式文档路径为 /api/docs，默认关闭。可在 config.json 中将 enable_api_docs 设为 true，或在启动环境中设置 OCTOP_ENABLE_API_DOCS=1。OpenAPI 模式位于 /api/openapi.json。

交互式 API 文档：
http://127.0.0.1:8088/api/docs

OpenAPI Schema：
http://127.0.0.1:8088/api/openapi.json

生产环境不建议把交互式文档无条件暴露到公网。即使文档页面可以打开，受保护接口仍需有效令牌和相应角色权限。

配置文件位于哪里

Octop 默认把运行状态放在 ~/.octop/。其中 config.json 保存地址、端口、跨域、数据库和 TLS 等进程级配置；可选的 env 文件采用 dotenv 格式；SQLite 数据库、日志、智能体工作区和密钥也位于该目录的不同子路径。

{
  "bind_host": "127.0.0.1",
  "port": 8088,
  "log_level": "info",
  "cors_origins": [],
  "default_timezone": "Asia/Shanghai",
  "enable_dashboard": true,
  "enable_api_docs": false,
  "require_setup_password": true,
  "database": {
    "driver": "sqlite",
    "sqlite_path": "octop.db"
  }
}

这是关键字段的精简示例，不应覆盖实际文件中的其他有效配置。修改后应重启服务并重新执行健康检查。

环境变量如何覆盖配置

官方配置文档规定，已设置的环境变量优先于 config.json 中的对应值；未设置的变量不会清空磁盘配置。OCTOP_HOME 可改变数据根目录，适合容器挂载或将状态迁移到专用磁盘。

Docker Compose 的 .env 主要用于变量插值，只有在 Compose 配置的 environment 中传入，变量才会进入容器。也可以把变量写入挂载后的 ~/.octop/env，由 Octop 启动时加载。

SQLite 与 PostgreSQL 如何选择

默认 SQLite 适合本机试用和轻量部署，无需单独维护数据库服务。多用户生产部署可以选择 PostgreSQL，并通过 OCTOP_DATABASE_URL 或一组 OCTOP_DATABASE_* 变量提供连接参数。

数据库密码宜通过环境变量或安全的密钥注入机制提供，避免提交到代码仓库。控制平面数据库与智能体记忆属于不同层次，切换控制平面到 PostgreSQL 不代表已有 SQLite 记忆会自动迁移。

首次初始化与无人值守部署

新实例首次访问会进入设置流程，用于选择数据库、创建管理员并完成初始化。命令行也可以执行 octop init。无人值守部署可使用 octop init --yes，并通过 OCTOP_ADMIN_USERNAME、OCTOP_ADMIN_PASSWORD 提供初始账号。

管理员密码属于敏感信息，不应写入镜像、公开 Compose 文件或构建日志。自动初始化完成后，还应检查设置向导是否关闭、管理员是否可登录以及数据库是否已正确绑定。

局域网和公网访问配置

默认 127.0.0.1 只接受本机连接。设置 OCTOP_BIND_HOST=0.0.0.0 可以所有网络接口，但这只是可达性设置，不提供访问保护。对外部署还需配置防火墙、HTTPS、反向代理和可信来源。

• 仅开放业务需要的端口，并限制管理入口来源。

• 按真实前端域名设置 CORS，不使用不必要的通配范围。

• 妥善保护 ~/.octop/secrets/jwt_secret 和模型 API Key。

• 为每个用户分配独立账号，避免共享管理员令牌。

• 升级或迁移前备份数据库、配置和智能体工作区。

常见问题排查

API 返回连接失败

先调用 /api/health，再检查进程、地址、端口映射和防火墙。容器内正常但宿主机无法访问时，应核对 Compose 或 Docker 的端口发布设置。

访问 /api/docs 返回 404

这通常是交互式文档仍处于关闭状态。设置 enable_api_docs 或对应环境变量后重启服务，再确认请求使用的是当前实例地址。

配置文件修改后没有生效

检查是否存在同名环境变量，因为它会覆盖文件值；同时确认修改的是当前 OCTOP_HOME 下的配置，并完成服务重启。

API 返回 401 或 403

401 通常与令牌缺失、过期或 JWT 密钥轮换有关；403 更可能表示当前用户角色或资源所有权不足。重新登录只能刷新令牌，不能提升权限。

总结

Octop AI 助手的官方源码入口是 TencentCloud/Octop 仓库，API 和 Dashboard 则由每个自托管实例提供。默认 API 基础地址为本机 8088 端口下的 /api，登录后使用 Bearer Token 调用受保护接口。部署时应掌握环境变量覆盖 config.json 的规则，并针对数据库、地址、CORS、TLS 和密钥保存制定明确配置。