★ FEATURED ARTICLE Octop 自托管 AI 助手 API 文档实战指南5 步从开启 /api/docs 到调通第一个接口【免费下载链接】OctopA smarter, self-hosted AI assistant — multi-user, multi-agent.项目地址: https://gitcode.com/GitHub_Trending/oct/OctopOctop 是一个多用户、多智能体协作的自托管 AI 助手全部后端能力挂在/api前缀下官方自带/api/docs交互文档与在线调试页。本文从打开文档页讲起覆盖 JWT 令牌获取与续期、分组导航、首次接口调通和错误码解读读完你能独立跑通第一条 API 请求链路。01 | 把文档页打开默认关闭、两种开启方式与验证动作/api/docs与/api/openapi.json出厂状态是关闭的访问直接 404——生产环境少暴露一层能力面这个取舍很合理。想打开它只有两个开关环境变量优先级高于配置文件开启方式写法生效条件配置文件~/.octop/config.json中加enable_api_docs: true重启服务环境变量OCTOP_ENABLE_API_DOCS1重启服务优先覆盖配置{ enable_api_docs: true }字段定义在 src/octop/config.py 的OctopConfig中/api/docs路由本身注册在 src/octop/api/app.py页面由 Scalar 渲染。验证动作重启后浏览器打开http://127.0.0.1:8088/api/docsOctop 默认监听127.0.0.1:8088看到左侧接口分组导航即算成功。 小贴士开启状态未走完首次安装向导时/api/docs本身能打开但调任何业务接口都会拿到 503 和{setup_required: true}——先完成向导再调试。02 | 拿到钥匙令牌获取与续期三步走登录换令牌POST /api/auth/login提交username与password响应里取access_token字段启用强验证码时还要带上captcha_token。请求头携带后续请求统一加Authorization: Bearer access_tokensrc/octop/api/middleware/jwt_auth.py 会对除白名单外的所有/api/*路由做拦截。过期与自动续期令牌 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/redeemOAuth 回调/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——分组有疑问直接翻这份源码对照。高频标签的能力边界标签管什么边界提醒setup首次安装向导建管理员、配模型只有初始安装阶段用得上auth登录登出、当前用户资料与偏好免令牌入口也在这agents智能体增删改查、启动/停止运行时运行时操作仅属主或管理员providersLLM 供应商与模型选择、连通性测试删除前确认无智能体引用cron挂在智能体上的定时 Promptowner only跨属主查不到browser远程浏览器会话、实时流、录放依赖宿主机浏览器环境点标签 → 右侧看接口卡片 → 按卡片上的 Bearer 标识决定是否带令牌导航就这三步。04 | 登录到调通一条请求链路完整走一遍目的接口权限探活GET /api/health公开登录POST /api/auth/login公开当前用户GET /api/auth/me用户智能体列表GET /api/agents用户启动智能体POST /api/agents/{id}/start属主建定时任务POST /api/agents/{id}/cron属主权限分四级递进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?tokenjwtJWT 放查询参数发送{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枚举一一对应。新手最常撞上的五个codeHTTP处理建议AUTH_FAILED/TOKEN_EXPIRED401重新走登录换新令牌LOGIN_LOCKED429等login_lockout_seconds解锁或请管理员调/api/users/{id}/unlock-loginSETUP_REQUIRED409初始管理员还没建先完成安装向导FORBIDDEN403令牌有效但角色不够升 admin 或换属主账号AGENT_NOT_FOUND404智能体不存在或不属于当前用户06 | 踩坑与生产建议5 个高频问答Q公网开着文档页会泄密吗文档页只暴露接口结构不含任何业务数据但它等于把系统能力边界摊开给扫描器。公网生产建议保持关闭确实需要时让反向代理给/api/docs单独加一层基础认证。Q文档页打不开怎么定位先看返回码404 说明enable_api_docs没开改完记得重启200 打开但业务接口全 503是安装向导没走完。Q想把文档能力搬进 Postman 或 YApiGET /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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
