如何在本地配置 PostHog Tasks 后台代理和 GitHub App 集成？
【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog
PostHog 的 Tasks（后台代理，background agents）功能允许在任务运行中启动沙箱、克隆仓库并驱动 agent 完成工作。要在本地跑通这条链路，需要完成两件配套的事：一是创建属于自己的个人开发用 GitHub App，并把四个GITHUB_APP_*凭据写进.env；二是运行setup_background_agents命令补齐数据库侧的 OAuth 应用、tasks功能开关和技能包，最后通过hogli start启动开发环境并在 Tasks 页面验证运行。本文基于仓库内的本地配置指南 docs/internal/sandboxes-setup-guide.md 整理，覆盖准备条件、GitHub App 两种创建路径、启动与验证方式，以及文档给出的已知故障排查表。
准备条件：本地环境需要满足什么
开始前先确认以下条件，它们来自指南和命令源码的要求：
- 开发环境可启动：
setup_background_agents会先检查数据库连接，数据库由hogli start拉起。命令在连不上数据库时会报Cannot connect to the database. Is the dev environment running? (hogli start)，即需要先有可启动的环境。 DEBUG=1必须开启：setup_background_agents与create_github_app都硬性要求 DEBUG 模式，否则会直接报CommandError。本地 Docker 沙箱（SANDBOX_PROVIDER=docker）同样要求DEBUG=1。- 每个工程师需要自己的 GitHub App：指南明确说明 GitHub App 是个人开发凭据，不能用生产 App 代替。
- 如果只想走 Docker 沙箱，指南推荐的本地组合是
SANDBOX_PROVIDER=docker，不需要 Modal 账号；setup_background_agents会从.env.example自动补全DEBUG、SANDBOX_PROVIDER等自动填充项（见 .env.example）。
创建 GitHub App：自动流程
指南提供了快捷命令create_github_app（实现见 products/signals/backend/management/commands/create_github_app.py），它通过 GitHub 的 App Manifest 流程自动化整个创建过程：
python manage.py create_github_app命令的行为与限制：
- 会在
127.0.0.1的--port（默认8019）上临时启动一个本地回调服务器，打开浏览器并预填 App 清单；你只需要在浏览器里单击一次 "Create GitHub App"，命令随即把GITHUB_APP_CLIENT_ID、GITHUB_APP_CLIENT_SECRET、GITHUB_APP_SLUG、GITHUB_APP_PRIVATE_KEY四个值写入.env，并验证私钥可用。 - 默认 base URL 为
http://localhost:8010，等待你完成浏览器操作的默认超时是 600 秒；超时或端口被占用时会报错并提示重新运行或换--port。 - 如果
.env或环境里已经存在这四个值，命令会先询问是否覆盖；非交互终端下必须显式加--force。 - 常用参数：
--org <name>表示在指定 GitHub 组织下创建（默认建在你当前登录的个人账号下）；--name指定 App 名称（默认随机生成PostHog Signals Dev <随机串>）；--no-browser不自动打开浏览器只打印 URL；--no-verify跳过创建后的私钥鉴权检查。 - 命令写入的 App 权限为 Contents（写）、Pull requests（写）、Metadata（读）、Issues（写）、Workflows（写）——后两项在指南中标注为可选，但命令默认包含以省去后续排错。
手动创建 GitHub App：权限、URL 与凭据
自动流程不可用时的手动步骤（指南中的参考路径），每一步都有对应用途：
在 GitHub 上进入 Settings → Developer Settings → GitHub Apps → New GitHub App。
Setup URL（注意是 Setup URL，不是 Callback 或 Homepage URL）设为：
http://localhost:8010/integrations/github/callbackCallback URL设为
http://localhost:8010/complete/github-link/——这个地址是 Code 的用户链接（user-link）流程使用的；实际上任意合法的 localhost URL 都可以，创建 App 时该字段必填。配置权限：
权限 访问级别 用途 Contents 读/写 读取文件、创建分支、推送提交 Pull requests 读/写 创建和更新 PR Metadata 只读 所有 GitHub App 必需 可选：Issues（读/写）、Workflows（读/写）。
在 "Identifying and authorizing users" 区域勾选Request user authorization (OAuth) during installation——个人用户链接流程依赖它。
在 App 页面的 "Client secrets" 下生成 client secret。指南特别提醒：这是近几个版本开始新增的必需项；如果本地环境最近突然不能工作，最可能缺的就是它。
生成private key，并把 App 安装到你的测试仓库：访问
http://localhost:8010/project/1/integrations/github完成安装。把四项凭据写入仓库根目录的
.env：# The OAuth Client ID (starts with Iv1 or Iv23) — NOT the numeric App ID. # Both fields are visible on the GitHub App settings page; the App ID is the # small grey number at the top, the Client ID is the labelled field below. GITHUB_APP_CLIENT_ID=Iv1.xxxxxxxxxxxxxxxx GITHUB_APP_CLIENT_SECRET=your_client_secret GITHUB_APP_SLUG=your-app-slug GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"占位符替换说明：
GITHUB_APP_CLIENT_ID填 App 设置页中以Iv1或Iv23开头的 OAuth Client ID（不是页面顶部灰色的小数字 App ID）；GITHUB_APP_SLUG填 App URL（形如github.com/apps/你的-slug）中 URL 友好的名字；私钥里的字面\n会被自动转换为换行符，直接整行粘贴即可。
运行 setup_background_agents：后台侧的本地代理配置
python manage.py setup_background_agents该命令幂等，可随时重复执行。按 products/tasks/backend/management/commands/setup_background_agents.py 的实现，它依次做五件事：
- 检查数据库连接，连不上会提示
hogli start。 - 补齐环境变量：把
.env.example中存在的OIDC_RSA_PRIVATE_KEY、SANDBOX_JWT_PRIVATE_KEY、DEBUG、SANDBOX_PROVIDER、SANDBOX_MCP_URL追加到.env（已存在的跳过）。排查表里提到的SANDBOX_JWT_PRIVATE_KEY缺失问题，重新运行本命令即可自动从.env.example回填。 - 创建 Array OAuth 应用（"Array Dev App"，client_type 为 public，授权码模式，重定向 URI 固定为本地开发用的四个回调地址）。
- 为每个 team 创建/恢复
tasks功能开关（100% 全量 rollout、active），这是 Tasks 页面可见和任务可执行的前提。 - 构建 agent 技能包（调用
products/posthog_ai/scripts/build_skills.py，输出会打印在命令日志里，耗时可能约一分钟）。
命令结束时输出Background agents setup complete!并提示运行hogli start。如果四个GITHUB_APP_*值还没写进.env，命令会打印上面手动步骤的摘要并询问是否打开 GitHub App 创建页。
另外两个命令值得了解：python manage.py setup_tasks_oauth用于补建 Array 和 PostHog AI 的开发用 OAuth 应用（当出现PostHog AI app not found for region ...时运行，实现在 products/tasks/backend/management/commands/setup_tasks_oauth.py；它在 US/EU 生产区域会自动跳过）；bin/migrate的部署流程也会执行它。
启动开发环境并在 Tasks 页面验证
hogli startTemporal 和 temporal-django-worker 会随hogli start通过 phrocs 自动启动，不需要单独拉起。指南描述了背后的process-task工作流（定义在products/tasks/backend/temporal/process_task/workflow.py）：依次执行get_task_processing_context（加载 TaskRun、校验 GitHub 集成与仓库）、get_sandbox_for_repository（创建 OAuth token、按需复用快照并克隆仓库）、start_agent_server（在沙箱内运行npx agent-server并轮询/health）、wait_condition（带 30 分钟不活动超时，由 agent 心跳延长，收到complete_task信号退出）、cleanup_sandbox（销毁沙箱容器，失败时也总是执行）。
UI 验证步骤（指南原文说明当前界面还比较简陋，但足以观察和调试后台云运行；也可以用 PostHog Desktop 代替调试界面）：
- 访问
/tasks打开 Tasks 页面——它不会出现在侧边栏，必须直接访问 URL，且前提是tasks功能开关已开启。 - 创建一个任务：填写标题、描述和仓库（格式：
owner/repo）。 - 点击 "Run task"。
- 在 session 视图中观察日志滚动输出。
如果任务卡住不动，结合下表的故障现象定位；排查无果时可看TaskRun状态或沙箱日志。
常见问题排查
下表整理自指南的 Troubleshooting 章节，均为文档原文给出的现象与对策：
| 现象 | 处理方式 |
|---|---|
| Docker not running | 启动 Docker Desktop 或 Docker 守护进程 |
| Temporal not reachable | 确认 Temporal 运行在127.0.0.1:7233，可用temporal server start-dev检查 |
| Feature flag not enabled | 重跑python manage.py setup_background_agents重新创建 100% rollout 的tasks开关 |
| Array OAuth app missing | 重跑python manage.py setup_background_agents |
PostHog AI app not found for region ... | 运行python manage.py setup_tasks_oauth补建 Array 与 PostHog AI 开发 App |
| GitHub token expired | GitHub App 安装产生的 token 约 1 小时过期，重跑任务获取新 token |
| "Task workflow execution blocked" | tasks功能开关未对该用户/组织开启 |
| Sandbox image build fails | 检查 Docker 磁盘空间，用docker system prune清理旧镜像 |
| Agent server health check fails | 查看沙箱日志：docker exec <container_id> cat /tmp/agent-server.log |
SANDBOX_JWT_PRIVATE_KEYmissing | 重跑python manage.py setup_background_agents，会自动从.env.example回填 |
| Port conflict on sandbox host port | DockerSandbox 把容器端口 47821 映射到动态宿主机端口；若被占用，停掉占用进程或重启 Docker |
| Sandbox can't reach PostHog API | Docker 下不要设置SANDBOX_API_URL（有自动转换）；确需覆盖时用 8000 端口而不是 8010（容器内访问 Caddy 会返回空响应） |
SANDBOX_PROVIDER=docker报sandbox is for local development only | 该 provider 要求DEBUG=1（或 pytest 的TEST=1）；flox 环境下DEBUG通常由环境注入，显式 unset 会触发该错误 |
git commit is disabled in PostHog Desktop | PATH shim（/opt/posthog/bin/git）拦截未签名的 commit/push；先git add再用git_signed_commit工具，调试时可设POSTHOG_ALLOW_UNSIGNED_GIT=1绕过 |
两点边界说明：docker与MODAL_DOCKER沙箱 provider 仅用于本地开发；若用 Modal 云沙箱，则无法直接访问localhost，需要额外配置隧道（Tailscale Funnel）和 Modal 凭据，见指南 "Testing with local agent packages" 一节。该节同时说明：只有当你修改@posthog/agent包时才需要配置LOCAL_POSTHOG_CODE_MONOREPO_ROOT等本地包相关项，否则可以整节忽略。
下一步
GitHub App 装好、setup_background_agents跑通、hogli start起来后，如果要在 Slack 中用@PostHog <task>触发运行代替 UI，参见 docs/internal/slack-local-setup-guide.md；需要修改 agent 包、MCP server 配置（services/mcp/.env）或遥测项时，回到 docs/internal/sandboxes-setup-guide.md 对应的 "Testing with local agent packages" 章节按条配置，每次改动.env后记得重启 temporal worker。
【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
