Coi支持6大AI编码工具:Claude Code、Codex、opencode、pi、omp配置与鉴权指南
Coi支持6大AI编码工具:Claude Code、Codex、opencode、pi、omp配置与鉴权指南
Coi(Code on Incus)是一款为 AI 编码智能体提供隔离沙箱机器的开源工具:每个 agent 运行在独立的 Linux 系统容器中,自带 root、Docker 与 systemd,却完全无法触碰你的宿主机。它内置支持 6 大 AI 编码工具——Claude Code、Codex、opencode、opencode2、pi、omp,通过一份 TOML 配置即可完成工具切换与鉴权,本文带你从零配好其中任意一个。
六大 AI 编码工具支持一览
Coi 的工具注册表位于 internal/tool/registry.go,共 6 个内置工具:
| 工具 | 配置名([tool] name) |
宿主机鉴权目录 | 镜像默认预装 |
|---|---|---|---|
| Claude Code | claude |
~/.claude |
✅(默认工具) |
| Codex CLI | codex |
~/.codex |
⛔ 需 opt-in |
| opencode(OpenCode v1) | opencode |
~/.config/opencode |
⛔ 需 opt-in |
| opencode2(OpenCode v2) | opencode2 |
~/.config/opencode |
✅ |
| pi | pi |
~/.pi/agent |
✅ |
| omp(Oh My Pi) | omp |
~/.omp |
⛔ 需 opt-in |
💡 镜像构建时默认安装
claude、opencode2、pi三个 agent(见 internal/tool/registry.go#L38-L40)。想装 Codex、omp 或 opencode v1,在配置中指定<a href="https://link.gitcode.com/i/7749fe782ea7b1fc3ba6f6ae15ed6c80" target="_blank">container.build] agents = ["claude", "codex", "omp"]后重新coi build即可,校验逻辑见 [internal/cli/build.go#L337-L351。
一键切换工具:配置文件的 3 种写法
🛠️ 写法一:全局配置(~/.coi/config.toml)或项目级配置(./.coi/config.toml):
[tool]
name = "codex" # 或 "claude"、"opencode"、"opencode2"、"pi"、"omp"
permission_mode = "bypass" # 自动放行(默认)或 "interactive" 逐次询问
📦 写法二:Profile 档案。用 coi profile create my-codex 生成档案后,在其 config.toml 里写入 [tool] name = "codex",之后一条命令启动:
coi shell --profile my-codex
📝 写法三:CLI 参数已移除。如果你还传 --tool,Coi 会直接报错并提示改为配置项(提示映射见 internal/cli/root.go#L263)。所有工具能力都收敛到配置文件里,团队可把 .coi/config.toml 提交到仓库共享同一套环境。
默认工具是 Claude Code,内置默认值定义在 profiles/default/config.toml#L67-L70。
鉴权原理:凭据如何安全进入容器
🔐 Coi 的核心原则是凭据默认不出宿主机。当你启动会话时,Coi 会按每个工具的"凭据包清单"把宿主机的登录文件复制进容器,而不是转发你的 SSH key 或环境变量。各工具需要复制的文件由 internal/tool/credentials/catalog.toml 统一定义:
- claude:
.credentials.json、settings.json、CLAUDE.md及状态文件.claude.json - codex:
auth.json、config.toml、AGENTS.md - pi / omp:
settings.json、models.json、auth.json、AGENTS.md - opencode / opencode2:
opencode.json、tui.json
几个新手友好的细节:
- 启动即审计:
coi shell启动时会打印"grants"报告,逐条列出哪些文件从宿主机复制进了容器(实现见 internal/session/setup_credentials.go#L11-L21),凭据流向一目了然。 - 缺文件不报错:宿主机没有
auth.json时直接跳过,会话照常启动(见 internal/session/setup_codex_test.go#L123-L125)。 - 令牌自动刷新:agent 在容器里刷新了登录令牌后,下次
--resume会用新令牌覆盖旧值。 - 额外凭据按需挂载:在 profile 里用
<a href="https://link.gitcode.com/i/5d6a82061f4b7591c9683794660dfaa3" target="_blank">[credentials]]条目即可复制任意宿主文件(例如bundle = "ollama"或自定义host/container路径对),格式定义见 [internal/config/types.go#L854-L872。
权限模式:bypass 还是 interactive
permission_mode 控制 agent 能否"无提示自动执行",各工具落地方式不同(源码均在各工具的 GetSandboxSettings/BuildCommand):
| 工具 | bypass(默认)行为 |
interactive 行为 |
|---|---|---|
| claude | 注入 --permission-mode bypassPermissions 并改写 settings.json 跳过权限弹窗(internal/tool/tool.go#L254-L294) |
保留 Claude 原始终端确认 |
| codex | 追加 --dangerously-bypass-approvals-and-sandbox(internal/tool/codex.go#L87-L117) |
-s workspace-write -a on-request |
| opencode / opencode2 | 向 opencode.json 注入 permission.*: "allow"(internal/tool/opencode.go#L88-L110) |
注入 "*": "ask" |
| pi / omp | 工具本身无权限门控,配置仅存档 | 同左 |
放心选择 bypass 的原因:真正的沙箱是 Incus 容器 + nftables 出站防火墙 + 内核级监控,检测到反弹 shell 等高危行为会自动暂停或终止容器。
工具专属微调参数
除了通用字段,Coi 还为 Claude 与 Codex 提供了专属旋钮(结构定义见 internal/config/types.go#L661-L684):
[tool.claude]
effort_level = "high" # low/medium/high/xhigh/max/auto,锁定 effort 等级
model = "opus" # 经 ANTHROPIC_MODEL 下发
[tool.codex]
model = "gpt-5-codex" # 经 -m 下发
reasoning_effort = "medium" # minimal/low/medium/high
其他通用字段:binary(替换可执行文件,如包装脚本)、pre_launch(启动前在容器内执行的命令)、context_file(自定义注入的 Markdown 上下文)、auto_context / context_json(自动注入沙箱上下文,默认开启,容器内会生成 ~/SANDBOX_CONTEXT.md 与 ~/SANDBOX_CONTEXT.json)。
⚡ 会话续接:coi shell --resume 会自动恢复最近会话;各工具的历史记录分别保存在 ~/.coi/sessions 下的 sessions-claude、sessions-codex 等目录,断线后用 coi attach 重新接入即可。
快速上手 3 步
# 1. 构建镜像(首次,默认含 claude/opencode2/pi;按需加 agents)
coi build
# 2. 在配置中选好 [tool] name(或用 profile)
# 3. 进入任意项目目录,开始编码会话
cd your-project
coi shell
会话出问题时可运行 coi health 端到端诊断环境。完整的命令速查(coi run、coi top、coi audit 等)见项目根目录的 README.md。
