Octop 自托管 AI 助手 API 文档实战指南：5 步从开启 /api/docs 到调通第一个接口

Octop 自托管 AI 助手 API 文档实战指南：5 步从开启 /api/docs 到调通第一个接口

【免费下载链接】OctopA smarter, self-hosted AI assistant — multi-user, multi-agent.项目地址: https://gitcode.com/GitHub_Trending/oct/Octop

Octop 是一个多用户、多智能体协作的自托管 AI 助手，全部后端能力挂在/api前缀下，官方自带/api/docs交互文档与在线调试页。本文从打开文档页讲起，覆盖 JWT 令牌获取与续期、分组导航、首次接口调通和错误码解读，读完你能独立跑通第一条 API 请求链路。

01 | 把文档页打开：默认关闭、两种开启方式与验证动作

/api/docs与/api/openapi.json出厂状态是关闭的，访问直接 404——生产环境少暴露一层能力面，这个取舍很合理。想打开它，只有两个开关，环境变量优先级高于配置文件：

{ "enable_api_docs": true }

字段定义在 src/octop/config.py 的OctopConfig中，/api/docs路由本身注册在 src/octop/api/app.py，页面由 Scalar 渲染。

验证动作：重启后浏览器打开http://127.0.0.1:8088/api/docs（Octop 默认监听127.0.0.1:8088），看到左侧接口分组导航即算成功。

💡 小贴士：开启状态未走完首次安装向导时，/api/docs本身能打开，但调任何业务接口都会拿到 503 和{"setup_required": true}——先完成向导再调试。

02 | 拿到钥匙：令牌获取与续期三步走

1. 登录换令牌：POST /api/auth/login提交username与password，响应里取access_token字段（启用强验证码时还要带上captcha_token）。
2. 请求头携带：后续请求统一加Authorization: Bearer <access_token>；src/octop/api/middleware/jwt_auth.py 会对除白名单外的所有/api/*路由做拦截。
3. 过期与自动续期：令牌 TTL 默认 86400 秒，由access_token_ttl_seconds控制。当剩余有效期不足三分之一时，认证响应会顺带一个X-Octop-Access-Token响应头，里面是新令牌——拿到就替换本地旧值，实现"一次登录长期在线"的滑动续期。

curl -s -X POST http://127.0.0.1:8088/api/auth/login \ -H "Content-Type: application/json" \ -d '{"username": "admin", "password": "你的密码"}'

以下端点免令牌，直接裸调：

• /api/docs、/api/openapi.json、/api/health
• /api/auth/login、/api/auth/captcha、SSO 系列/api/auth/oidc/*、/api/auth/oauth/*
• 邀请码：/api/auth/invite/validate、/api/auth/invite/redeem；OAuth 回调/api/connectors/oauth/callback；内部网关/api/internal/mcp/*
• 首次安装向导/api/setup/*

注意安装锁：首个管理员创建之前，src/octop/api/middleware/setup_lockdown.py 会对所有非公开/api接口一律回 503setup_required，等于强制你先走安装向导。

03 | 看懂左侧地图：40 多个标签的分组逻辑

文档页左侧 40 多个业务标签，不是拍脑袋起的，而是OPENAPI_TAGS配置逐条生成，定义在 src/octop/api/openapi_meta.py——分组有疑问直接翻这份源码对照。高频标签的能力边界：

点标签 → 右侧看接口卡片 → 按卡片上的 Bearer 标识决定是否带令牌，导航就这三步。

04 | 登录到调通：一条请求链路完整走一遍

权限分四级递进：public → user → owner → admin。owner 指资源属主或管理员，例如 cron 接口即使管理员去看别人的任务也拿不到数据。文档页右侧接口卡片上的BearerAuth标识可以直接看出该接口属于哪一级。

在线调试演示两个高频动作。第一步，文档页找到POST /api/auth/login，填入username、password点发送，从响应 JSON 取出access_token；第二步，在请求设置里配置全局头：

Authorization: Bearer 刚才复制的令牌

再调GET /api/auth/me，返回{id, username, role, ...}即代表鉴权链路完全跑通。

实时对话不走 HTTP：连WS /api/agents/{agent_id}/chat/ws?token=<jwt>（JWT 放查询参数），发送{"type":"user_turn", ...}帧，服务端流式回 JSON 分片，直到done或error帧。

05 | 错误码怎么读：统一信封 + 5 个高频码

所有非 2xx 的 JSON 响应都是同一副信封，message会按Accept-Language本地化：

{ "error": { "code": "AGENT_NOT_FOUND", "message": "...", "details": {} } }

code与 src/octop/infra/errors.py 的ErrorCode枚举一一对应。新手最常撞上的五个：

06 | 踩坑与生产建议：5 个高频问答

Q：公网开着文档页会泄密吗？文档页只暴露接口结构，不含任何业务数据；但它等于把系统能力边界摊开给扫描器。公网生产建议保持关闭，确实需要时让反向代理给/api/docs单独加一层基础认证。

Q：文档页打不开，怎么定位？先看返回码：404 说明enable_api_docs没开（改完记得重启）；200 打开但业务接口全 503，是安装向导没走完。

Q：想把文档能力搬进 Postman 或 YApi？GET /api/openapi.json拉完整规范，导入即可离线维护集合。

Q：批量脚本总是令牌过期？在请求层加一行逻辑：每次响应检查X-Octop-Access-Token，存在就替换本地令牌——续期是服务端顺带完成的，别自己算时间。

Q：文档页和 Swagger 能共存吗？不用纠结。Octop 只保留 Scalar 这一套，/api/docs就是唯一入口。

这套"开页 → 拿令牌 → 看分组 → 调通首个接口 → 读懂错误 → 生产避坑"的闭环走完，Octop 的 HTTP API 就真正成了你的工具箱。想进一步挖接口细节，直接翻官方 docs/api.md 与 docs/configuration.md。

【免费下载链接】OctopA smarter, self-hosted AI assistant — multi-user, multi-agent.项目地址: https://gitcode.com/GitHub_Trending/oct/Octop