Coder Agents 上手：把AI编程Agent部署到自己的服务器上

为什么要自托管AI编程Agent

用 Claude Code、Cursor、Codex 写代码，已经是很多开发者的日常。但如果你在金融、政府、医疗这类行业工作，一个绕不开的问题是：代码要发到第三方云端。

Coder 在 5 月 6 日发布了 Coder Agents beta。一个 AI 编程 Agent，整套系统跑在你自己的服务器上，控制面、编排层、执行环境都在内网。源码、prompt、模型交互不出去。

这篇文章记录我从零部署 Coder Agents 的过程，包括踩过的坑。

Coder Agents 和其他工具的区别

先说清楚 Coder Agents 不是什么：它不是 Claude Code 或 Codex 的封装。它有自己的原生 Agent，走自己的编排逻辑。

几个工具的定位对比：

• Claude Code / Codex：云端编排，代码和 prompt 经过厂商服务器，适合个人开发者和小团队
• Cursor Agent：本地 IDE 集成，但推理仍然走云端 API
• Coder Agents：控制面+编排+执行全部自托管，支持接任意模型（Anthropic、OpenAI、Google、AWS Bedrock、自建模型）

Coder 自己的调研数据：61% 的工程团队已经在用 AI Agent，但其中 70% 部署在不合适的基础设施上。这个数字我觉得偏保守，我见过不少团队直接用个人账号的 Claude Code 跑公司代码的。

部署前准备

你需要这些东西：

1. 一个跑着最新版的 Coder 部署（版本 ≥ 2.33.1）
2. 至少一个 LLM 厂商的 API key（Anthropic、OpenAI、Google 都行）
3. 控制面到 LLM 厂商的网络通路（注意：工作区不需要 LLM 访问权限，只有控制面需要）
4. 至少一个模板（template），写好名称和描述

如果你还没有 Coder 环境，先装一个：

# 用 Docker 快速拉起
curl -fsSL https://coder.com/install.sh | sh

# 或者 Kubernetes 部署（生产环境推荐）
helm repo add coder-v2 https://helm.coder.com/v2
helm install coder coder-v2/coder \
  --namespace coder \
  --create-namespace \
  --values values.yaml

配置 LLM 模型

这一步需要 Owner 权限。普通用户看不到管理面板。

1. 进入 Coder 管理后台，点 Agents 页面
2. 打开 Settings > Manage Agents，选 Providers 标签页
3. 选一个厂商，填 API key，保存
4. 切到 Models 标签页，点 Add，填模型标识符、显示名称、上下文长度限制
5. 点模型旁边的星号图标，设为默认模型

我的建议是先配一个主力模型跑通流程，别一上来就接好几个。我第一次部署时同时配了三个厂商，结果花了一个小时排查网络问题，其实只是 Azure OpenAI 的 endpoint 格式写错了。

# values.yaml 中的模型配置示例（Kubernetes 部署时）
env:
  - name: CODER_AGENTS_PROVIDER_ANTHROPIC_API_KEY
    valueFrom:
      secretKeyRef:
        name: coder-secrets
        key: anthropic-api-key

如果是气隙环境（air-gapped），可以接自建的模型。比如用 vLLM 跑 Llama 或 Mistral：

# 自建模型的 endpoint 配置
# Provider 选 "OpenAI Compatible"
# Base URL 填你的 vLLM 服务地址
# 例如：http://vllm.internal:8000/v1

给用户分配权限

Coder Agents 有一个专门的角色叫 Coder Agents User。这个角色按组织（organization）分配，用户默认没有。Owner 角色自动有权限，不需要额外配。

在管理后台操作：

1. Admin settings > Organizations > 选你的组织
2. Members 标签页里找到用户
3. 点 Roles 那一列，打开 Coder Agents User，保存

如果用户多，用 CLI 批量操作：

# 给单个用户加角色（保留原有角色）
ORG="my-org"
USER="alice"
ROLES=$(coder organizations members list -O "$ORG" -o json \
  | jq -r --arg user "$USER" \
      '.[] | select(.username == $user) | [.roles[].name, "agents-access"]
      | unique | join(" ")')
coder organizations members edit-roles "$USER" -O "$ORG" $ROLES

注意 edit-roles 是替换操作，不是追加。漏掉原来的角色，用户现有权限就没了。我第一次操作时把一个同事的 template-admin 角色搞丢了，他当天就过来问为什么模板改不了了。

如果要给组织里所有人加权限：

ORG="my-org"
coder organizations members list -O "$ORG" -o json \
  | jq -c '.[] | {user_id, roles: [.roles[].name]}' \
  | while read -r row; do
      user_id=$(echo "$row" | jq -r '.user_id')
      roles=$(echo "$row" | jq -r '(.roles + ["agents-access"]) | unique | join(" ")')
      coder organizations members edit-roles "$user_id" -O "$ORG" $roles
    done

跑第一个任务

配好之后，进 Coder 后台的 Agents 页面，选一个模型，输入 prompt。

Agent 的执行逻辑分两种情况：

• 不需要代码执行的任务（架构讨论、方案规划、问答）：直接在控制面处理，没有启动延迟
• 需要代码执行的任务（写代码、跑测试、分析仓库、开 PR）：Agent 自动选一个模板，拉起一个工作区，在里面执行

# 示例 prompt
"分析 /repo/backend 目录的代码结构，找出重复代码，给出重构建议，并为核心模块补充单元测试"

Agent 会自动选模板、创建工作区、克隆代码、执行分析。完成后你能看到它的操作记录。

踩坑记录

部署过程中碰到的问题：

1. 模板描述太模糊导致 Agent 选错模板

Agent 根据模板的 name 和 description 选工作区模板，它不读 Terraform 代码。如果你的模板描述写的是"开发环境"，Agent 大概率选错。改成具体的，比如"Python 3.11 后端开发环境，预装 PostgreSQL 和 Redis"。

2. 控制面内存不够

Agent 的编排逻辑跑在控制面上，比普通的 Coder 部署更吃内存。我们原来给控制面分了 2GB，跑 Agent 时偶尔 OOM。加到 4GB 后稳定了。如果同时跑多个 Agent 任务，建议 8GB 起步。

3. 网络策略阻断了控制面到 LLM 的请求

在 Kubernetes 环境里，如果有 NetworkPolicy，记得放行控制面 Pod 到 LLM API endpoint 的出站流量。工作区 Pod 不需要，只有控制面需要访问 LLM。

4. Beta 阶段的限制

Beta 期间（到 2026 年 9 月）没有用量限制，功能全开放。但官方说了 API 和配置可能随版本变化，生产环境用的话建议锁定版本号。

什么场景值得用

不是所有团队都需要 Coder Agents。适合的场景：代码不能出内网的行业（金融、政务、军工、医疗），需要集中管控 AI 工具使用的中大型团队，想按任务切换不同模型的组织，以及已经在用 Coder 的团队（接入成本最低）。

个人开发者或小团队没有合规压力的话，Claude Code 和 Cursor 上手更快。Coder Agents 解决的是"能不能用"的问题。很多企业场景里，云端 AI 编程工具的答案就是"不能用"，这才是它的价值。

小结

Coder Agents 的 beta 到 9 月前免费，功能不限。团队一直被安全合规卡着用不了 AI 编程工具的，可以趁这个窗口试试。

部署步骤：装 Coder ≥ 2.33.1 → 配 LLM 厂商和模型 → 给用户分配 Agents 角色 → 写好模板描述 → 开始用。主要时间花在网络配置和模板优化上，Agent 本身不需要太多调整。

参考文档：https://coder.com/docs/ai-coder/agents/getting-started