docs: document codex robot connect command

2026-06-10 20:44:45 +08:00
parent 864f94e80e
commit 2c1be7a8fb
3 changed files with 33 additions and 0 deletions
@@ -108,12 +108,24 @@ dws devapp robot connect --channel auto --robot-client-id <clientId> --robot-cli
 # 用统一应用 ID，复用 credentials get 自动取凭证
 dws devapp robot connect --unified-app-id <unifiedAppId> --channel qoderwork

+# Codex 渠道推荐显式覆盖 agent 命令；否则默认空白工作目录可能触发
+# "Not inside a trusted directory and --skip-git-repo-check was not specified"
+CODEX_BIN="$(command -v codex || echo /Applications/Codex.app/Contents/Resources/codex)"
+DWS_AGENT_CMD="$CODEX_BIN exec --skip-git-repo-check" \
+  dws devapp robot connect --unified-app-id <unifiedAppId> --channel codex --format json
+
 # 预览建联方案不实际起连接
 dws devapp robot connect --robot-client-id <clientId> --robot-client-secret <clientSecret> --dry-run --format json
 ```

 只建联、不建号：缺凭证先用 `robot create` / `robot submit` 建号拿 clientId/clientSecret。

+Codex 渠道注意：
+
+- `--channel codex` 真实建联时，优先使用上面的 `DWS_AGENT_CMD="$CODEX_BIN exec --skip-git-repo-check"` 形式，避免 Codex CLI 在默认临时目录内因非可信 Git 目录拒绝执行。
+- 如需给 Codex 固定知识/项目上下文，可把可信目录直接写进覆盖命令：`DWS_AGENT_CMD="$CODEX_BIN exec --skip-git-repo-check -C /path/to/repo"`。路径不要包含空格。
+- 设置 `DWS_AGENT_CMD` 后，DWS 不再自动拼接 `--agent-model` / `--agent-workdir` / 会话参数；需要的参数要一起写进 `DWS_AGENT_CMD`。
+
 | flag | 说明 |
 |------|------|
 | `--channel` | `auto`(默认,运行时信号自动识别) / openclaw / qoder / qoderwork / hermes / workbuddy / claudecode / codebuddy / codex / gemini / opencode |
@@ -134,5 +146,6 @@ dws devapp robot connect --robot-client-id <clientId> --robot-client-secret <cli
 |------|------|
 | `robot info is not exist` | 应用未配置机器人，先用 `robot config` 创建 |
 | 应用名重复 | `app-name` 企业内需唯一，换个名字 |
+| 本地 Codex agent 返回 `Not inside a trusted directory and --skip-git-repo-check was not specified` | 用 `DWS_AGENT_CMD="$CODEX_BIN exec --skip-git-repo-check"` 重启 `robot connect --channel codex` |
 | `ServiceResult.success=false` | 透传 `errorCode/errorMsg` |
 | 创建任务 `EXPIRED` | 任务过期，重新 `submit`（可带原 taskId 重试） |
@@ -212,6 +212,12 @@ dws devapp robot connect --channel auto --robot-client-id CLIENT_ID --robot-clie
 # 用统一应用 ID，复用 credentials get 自动取凭证（省得手填）
 dws devapp robot connect --unified-app-id UNIFIED_APP_ID --channel qoderwork

+# Codex 渠道推荐显式覆盖 agent 命令；否则默认临时目录可能触发
+# "Not inside a trusted directory and --skip-git-repo-check was not specified"
+CODEX_BIN="$(command -v codex || echo /Applications/Codex.app/Contents/Resources/codex)"
+DWS_AGENT_CMD="$CODEX_BIN exec --skip-git-repo-check" \
+  dws devapp robot connect --unified-app-id UNIFIED_APP_ID --channel codex --format json
+
 # 预览建联方案不实际起连接
 dws devapp robot connect --robot-client-id CLIENT_ID --robot-client-secret CLIENT_SECRET --dry-run --format json
 ```
@@ -223,6 +229,7 @@ dws devapp robot connect --robot-client-id CLIENT_ID --robot-client-secret CLIEN
 - **会话记忆 `--agent-memory`**（默认开）：同一群/单聊共享 agent 会话，追问保留上下文。仅 claudecode/codebuddy/workbuddy 支持（CLI 有 `--session-id/--resume`）；其余渠道自动无状态。`--agent-memory=false` 关闭。
 - **模型覆盖 `--agent-model`**：claudecode 默认锁 haiku 求快，可改 sonnet/opus 换聪明（env `DWS_AGENT_MODEL`）。
 - **运行目录 `--agent-workdir`**：放知识文件给机器人企业上下文；默认空白临时目录求快（env `DWS_AGENT_WORKDIR`）。
+- **Codex 渠道**：真实建联优先用 `DWS_AGENT_CMD="$CODEX_BIN exec --skip-git-repo-check"`，避免 Codex CLI 在默认临时目录内拒绝执行。需要固定上下文时，把可信目录写进覆盖命令：`DWS_AGENT_CMD="$CODEX_BIN exec --skip-git-repo-check -C /path/to/repo"`（路径不要包含空格）。设置 `DWS_AGENT_CMD` 后，DWS 不再自动拼接 `--agent-model/--agent-workdir/会话参数`。
 - **stream-bridge 渠道**（qoder/qoderwork/claudecode/workbuddy/codex/gemini/opencode）：Go 原生进程内 Stream 转发器，订阅 `TOPIC_ROBOT`，每条 @机器人消息起一个无头 CLI 实例（如 `claude -p`）→ stdout 回钉钉，可 7×24 无人值守。
 - **官方渠道**（openclaw/hermes）：dws 不代建机器人，输出官方 onboarding 指引（连接器自带建号 + AI 卡片回复）。
 - 覆盖项：`DWS_AGENT_CMD`(指定 agent 可执行命令) / `DWS_CONNECT_CMD`(指定外部连接器) / `DWS_CONNECT_NO_INSTALL=1`(关闭缺包自动安装) / `DWS_AGENT_TIMEOUT_MS`。
@@ -108,12 +108,24 @@ dws devapp robot connect --channel auto --robot-client-id <clientId> --robot-cli
 # 用统一应用 ID，复用 credentials get 自动取凭证
 dws devapp robot connect --unified-app-id <unifiedAppId> --channel qoderwork

+# Codex 渠道推荐显式覆盖 agent 命令；否则默认空白工作目录可能触发
+# "Not inside a trusted directory and --skip-git-repo-check was not specified"
+CODEX_BIN="$(command -v codex || echo /Applications/Codex.app/Contents/Resources/codex)"
+DWS_AGENT_CMD="$CODEX_BIN exec --skip-git-repo-check" \
+  dws devapp robot connect --unified-app-id <unifiedAppId> --channel codex --format json
+
 # 预览建联方案不实际起连接
 dws devapp robot connect --robot-client-id <clientId> --robot-client-secret <clientSecret> --dry-run --format json
 ```

 只建联、不建号：缺凭证先用 `robot create` / `robot submit` 建号拿 clientId/clientSecret。

+Codex 渠道注意：
+
+- `--channel codex` 真实建联时，优先使用上面的 `DWS_AGENT_CMD="$CODEX_BIN exec --skip-git-repo-check"` 形式，避免 Codex CLI 在默认临时目录内因非可信 Git 目录拒绝执行。
+- 如需给 Codex 固定知识/项目上下文，可把可信目录直接写进覆盖命令：`DWS_AGENT_CMD="$CODEX_BIN exec --skip-git-repo-check -C /path/to/repo"`。路径不要包含空格。
+- 设置 `DWS_AGENT_CMD` 后，DWS 不再自动拼接 `--agent-model` / `--agent-workdir` / 会话参数；需要的参数要一起写进 `DWS_AGENT_CMD`。
+
 | flag | 说明 |
 |------|------|
 | `--channel` | `auto`(默认,运行时信号自动识别) / openclaw / qoder / qoderwork / hermes / workbuddy / claudecode / codebuddy / codex / gemini / opencode |
@@ -134,5 +146,6 @@ dws devapp robot connect --robot-client-id <clientId> --robot-client-secret <cli
 |------|------|
 | `robot info is not exist` | 应用未配置机器人，先用 `robot config` 创建 |
 | 应用名重复 | `app-name` 企业内需唯一，换个名字 |
+| 本地 Codex agent 返回 `Not inside a trusted directory and --skip-git-repo-check was not specified` | 用 `DWS_AGENT_CMD="$CODEX_BIN exec --skip-git-repo-check"` 重启 `robot connect --channel codex` |
 | `ServiceResult.success=false` | 透传 `errorCode/errorMsg` |
 | 创建任务 `EXPIRED` | 任务过期，重新 `submit`（可带原 taskId 重试） |